Merge branch 'simplify-docs-review-app-trigger' into 'master'

Simplify the triggerring of 'gitlab-docs' Review App pipelines

See merge request gitlab-org/gitlab!53361

.gitlab/ci/docs.gitlab-ci.yml

@@ -10,17 +10,18 @@
     # because some repos are private and CI_JOB_TOKEN cannot access files.
     # See https://gitlab.com/gitlab-org/gitlab/issues/191273
     GIT_DEPTH: 1
+    # By default, deploy the Review App using the `master` branch of the `gitlab-org/gitlab-docs` project
+    DOCS_BRANCH: master
   environment:
-    name: review-docs/$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID
+    name: review-docs/mr-${CI_MERGE_REQUEST_IID}
     # DOCS_REVIEW_APPS_DOMAIN and DOCS_GITLAB_REPO_SUFFIX are CI variables
     # Discussion: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/14236/diffs#note_40140693
     auto_stop_in: 2 weeks
-    url: http://docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID.$DOCS_REVIEW_APPS_DOMAIN/$DOCS_GITLAB_REPO_SUFFIX
+    url: http://${DOCS_BRANCH}-${DOCS_GITLAB_REPO_SUFFIX}-${CI_MERGE_REQUEST_IID}.${DOCS_REVIEW_APPS_DOMAIN}/${DOCS_GITLAB_REPO_SUFFIX}
     on_stop: review-docs-cleanup
   before_script:
-    - apk add --update openssl
-    - gem install httparty --no-document --version 0.17.3
-    - gem install gitlab --no-document --version 4.13.0
+    - source ./scripts/utils.sh
+    - install_gitlab_gem
 
 # Always trigger a docs build in gitlab-docs only on docs-only branches.
 # Useful to preview the docs changes live.
@@ -33,7 +34,7 @@ review-docs-deploy:
 review-docs-cleanup:
   extends: .review-docs
   environment:
-    name: review-docs/$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID
+    name: review-docs/mr-${CI_MERGE_REQUEST_IID}
     action: stop
   script:
     - ./scripts/trigger-build docs cleanup

doc/development/documentation/index.md

@@ -387,11 +387,13 @@ To preview your changes to documentation locally, follow this
 The live preview is currently enabled for the following projects:
 
 - [`gitlab`](https://gitlab.com/gitlab-org/gitlab)
+- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab)
 - [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner)
 
 If your merge request has docs changes, you can use the manual `review-docs-deploy` job
 to deploy the docs review app for your merge request.
-You need at least Maintainer permissions to be able to run it.
+As the job creates a pipeline in `gitlab-org/gitlab-docs`, you need at least Maintainer
+permission in the `gitlab-org/gitlab-docs` project in order to successfully run the job.
 
 ![Manual trigger a docs build](img/manual_build_docs.png)
 
@@ -399,11 +401,6 @@ You must push a branch to those repositories, as it doesn't work for forks.
 
 The `review-docs-deploy*` job:
 
-1. Creates a new branch in the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs)
-   project named after the scheme: `docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID`,
-   where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ee` for
-   EE, `omnibus` for Omnibus GitLab, etc, and `CI_MERGE_REQUEST_IID` is the ID
-   of the respective merge request.
 1. Triggers a cross project pipeline and build the docs site with your changes.
 
 In case the review app URL returns 404, this means that either the site is not
@@ -412,11 +409,6 @@ minutes and it should appear online, otherwise you can check the status of the
 remote pipeline from the link in the merge request's job output.
 If the pipeline failed or got stuck, drop a line in the `#docs` chat channel.
 
-Make sure that you always delete the branch of the merge request you were
-working on. If you don't, the remote docs branch isn't removed either,
-and the server where the Review Apps are hosted can eventually run out of
-disk space.
-
 NOTE:
 Someone with no merge rights to the GitLab projects (think of forks from
 contributors) cannot run the manual job. In that case, you can

scripts/trigger-build

@@ -214,15 +214,7 @@ module Trigger
     => If something doesn't work, drop a line in the #docs chat channel.
     MSG
 
-    # Create a remote branch in gitlab-docs and immediately cancel the pipeline
-    # to avoid race conditions, since a triggered pipeline will also run right
-    # after the branch creation. This only happens the very first time a branch
-    # is created and will be skipped in subsequent runs. Read more in
-    # https://gitlab.com/gitlab-org/gitlab-docs/issues/154.
-    #
     def deploy!
-      create_remote_branch!
-      cancel_latest_pipeline!
       invoke!.wait!
       display_success_message
     end
@@ -231,31 +223,47 @@ module Trigger
     # Remove a remote branch in gitlab-docs.
     #
     def cleanup!
-      gitlab_client(:downstream).delete_branch(downstream_project_path, ref)
-      puts "=> Remote branch '#{downstream_project_path}' deleted"
+      environment = gitlab_client(:downstream).environments(downstream_project_path, name: downstream_environment).first
+      return unless environment
+
+      environment = gitlab_client(:downstream).stop_environment(downstream_project_path, environment.id)
+      if environment.state == 'stopped'
+        puts "=> Downstream environment '#{downstream_environment}' stopped"
+      else
+        puts "=> Downstream environment '#{downstream_environment}' failed to stop."
+      end
     end
 
     private
 
+    def downstream_environment
+      "review/#{ref}#{review_slug}"
+    end
+
+    # We prepend the `-` here because we cannot use variable substitution in `environment.name`/`environment.url`
+    # Some projects (e.g. `omnibus-gitlab`) use this script for branch pipelines, so we fallback to using `CI_COMMIT_REF_SLUG` for those cases.
+    def review_slug
+      identifier = ENV['CI_MERGE_REQUEST_IID'] || ENV['CI_COMMIT_REF_SLUG']
+
+      "-#{project_slug}-#{identifier}"
+    end
+
     def downstream_project_path
       ENV['DOCS_PROJECT_PATH'] || 'gitlab-org/gitlab-docs'
     end
 
     def ref
-      if ENV['CI_MERGE_REQUEST_IID'].nil?
-        "docs-preview-#{slug}-#{ENV['CI_COMMIT_REF_SLUG']}"
-      else
-        "docs-preview-#{slug}-#{ENV['CI_MERGE_REQUEST_IID']}"
-      end
+      ENV['DOCS_BRANCH'] || 'master'
     end
 
     def extra_variables
       {
-        "BRANCH_#{slug.upcase}" => ENV['CI_COMMIT_REF_NAME']
+        "BRANCH_#{project_slug.upcase}" => ENV['CI_COMMIT_REF_NAME'],
+        "REVIEW_SLUG" => review_slug
       }
     end
 
-    def slug
+    def project_slug
       case ENV['CI_PROJECT_PATH']
       when 'gitlab-org/gitlab-foss'
         'ce'
@@ -270,37 +278,14 @@ module Trigger
       end
     end
 
+    # app_url is the URL of the `gitlab-docs` Review App URL defined in
+    # https://gitlab.com/gitlab-org/gitlab-docs/-/blob/b38038132cf82a24271bbb294dead7c2f529e275/.gitlab-ci.yml#L383
     def app_url
-      "http://#{ref}.#{ENV['DOCS_REVIEW_APPS_DOMAIN']}/#{slug}"
-    end
-
-    def create_remote_branch!
-      gitlab_client(:downstream).create_branch(downstream_project_path, ref, 'master')
-      puts "=> Remote branch '#{ref}' created"
-    rescue Gitlab::Error::BadRequest
-      puts "=> Remote branch '#{ref}' already exists!"
-    end
-
-    def cancel_latest_pipeline!
-      pipelines = nil
-
-      # Wait until the pipeline is started
-      loop do
-        sleep 1
-        puts "=> Waiting for pipeline to start..."
-        pipelines = gitlab_client(:downstream).pipelines(downstream_project_path, { ref: ref })
-        break if pipelines.any?
-      end
-
-      # Get the first pipeline ID which should be the only one for the branch
-      pipeline_id = pipelines.first.id
-
-      # Cancel the pipeline
-      gitlab_client(:downstream).cancel_pipeline(downstream_project_path, pipeline_id)
+      "http://#{ref}#{review_slug}.#{ENV['DOCS_REVIEW_APPS_DOMAIN']}/#{project_slug}"
     end
 
     def display_success_message
-      format(SUCCESS_MESSAGE, app_url: app_url)
+      puts format(SUCCESS_MESSAGE, app_url: app_url)
     end
   end
 

scripts/utils.sh

@@ -32,7 +32,7 @@ function install_api_client_dependencies_with_apt() {
 
 function install_gitlab_gem() {
   gem install httparty --no-document --version 0.18.1
-  gem install gitlab --no-document --version 4.14.1
+  gem install gitlab --no-document --version 4.17.0
 }
 
 function install_tff_gem() {