Use the MR IID in the docs Review Apps URLsdocs/test-merge

We're taking advantage of the pipelines for merge requests
https://docs.gitlab.com/ee/ci/merge_request_pipelines/.

This will result in a nicer URL which will be more informative
than the previous one where a string of random characters was used.

3 files changed, 33 insertions, 36 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 45de5ce61c6..3424b44193c 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -255,10 +255,10 @@ package-and-qa:
     <<: *single-script-job-variables
     SCRIPT_NAME: trigger-build-docs
   environment:
-    name: review-docs/$CI_COMMIT_REF_SLUG
+    name: review-docs/$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID
     # DOCS_REVIEW_APPS_DOMAIN and DOCS_GITLAB_REPO_SUFFIX are CI variables
     # Discussion: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14236/diffs#note_40140693
-    url: http://$CI_ENVIRONMENT_SLUG.$DOCS_REVIEW_APPS_DOMAIN/$DOCS_GITLAB_REPO_SUFFIX
+    url: http://docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID.$DOCS_REVIEW_APPS_DOMAIN/$DOCS_GITLAB_REPO_SUFFIX
     on_stop: review-docs-cleanup
 
 # Trigger a manual docs build in gitlab-docs only on non docs-only branches.
@@ -271,8 +271,8 @@ review-docs-deploy-manual:
     - ./$SCRIPT_NAME deploy
   when: manual
   only:
-    - branches@gitlab-org/gitlab-ce
-    - branches@gitlab-org/gitlab-ee
+    - merge_requests@gitlab-org/gitlab-ce
+    - merge_requests@gitlab-org/gitlab-ee
   <<: *except-docs-and-qa
 
 # Always trigger a docs build in gitlab-docs only on docs-only branches.
@@ -284,8 +284,11 @@ review-docs-deploy:
     - gem install gitlab --no-document
     - ./$SCRIPT_NAME deploy
   only:
-    - /(^docs[\/-].*|.*-docs$)/@gitlab-org/gitlab-ce
-    - /(^docs[\/-].*|.*-docs$)/@gitlab-org/gitlab-ee
+    refs:
+      - merge_requests@gitlab-org/gitlab-ce
+      - merge_requests@gitlab-org/gitlab-ee
+    variables:
+      - $CI_COMMIT_REF_NAME =~ /(^docs[\/-].*|.*-docs$)/
   <<: *except-qa
 
 # Cleanup remote environment of gitlab-docs
@@ -293,15 +296,15 @@ review-docs-cleanup:
   <<: *review-docs
   stage: post-cleanup
   environment:
-    name: review-docs/$CI_COMMIT_REF_SLUG
+    name: review-docs/$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID
     action: stop
   script:
     - gem install gitlab --no-document
     - ./$SCRIPT_NAME cleanup
   when: manual
   only:
-    - branches@gitlab-org/gitlab-ce
-    - branches@gitlab-org/gitlab-ee
+    - merge_requests@gitlab-org/gitlab-ce
+    - merge_requests@gitlab-org/gitlab-ee
 
 ##
 # Trigger a docker image build in CNG (Cloud Native GitLab) repository
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index 828f9bfeec6..e9fad3a6f88 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -434,10 +434,10 @@ You will need to push a branch to those repositories, it doesn't work for forks.
 The `review-docs-deploy*` job will:
 
 1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-com/gitlab-docs)
-   project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`,
+   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, `ce` for
-   CE, etc.
-1. Trigger a cross project pipeline and build the docs site with your changes
+   CE, etc., and the `CI_MERGE_REQUEST_IID` the number of the merge request.
+1. Trigger a cross project pipeline and build the docs site with your changes.
 
 After a few minutes, the Review App will be deployed and you will be able to
 preview the changes. The docs URL can be found in two places:
@@ -459,30 +459,25 @@ disk space.
 
 ### Troubleshooting review apps
 
-In case the review app URL returns 404, follow these steps to debug:
-
-1. **Did you follow the URL from the merge request widget?** If yes, then check if
-   the link is the same as the one in the job output.
-1. **Did you follow the URL from the job output?** If yes, then it means that
-   either the site is not yet deployed or something went wrong with the remote
-   pipeline. Give it a few minutes and it should appear online, otherwise you
-   can check the status of the remote pipeline from the link in the job output.
-   If the pipeline failed or got stuck, drop a line in the `#docs` chat channel.
+In case the review app URL returns 404, this means that either the site is not
+yet deployed, or something went wrong with the remote pipeline. Give it a few
+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.
 
 ### Technical aspects
 
 If you want to know the in-depth details, here's what's really happening:
 
-1. You manually run the `review-docs-deploy` job in a CE/EE merge request.
-1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs)
+1. The `review-docs-deploy` job is run in a merge request.
+1. The job executes the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs)
    script with the `deploy` flag, which in turn:
-   1. Takes your branch name and applies the following:
-      - The slug of the branch name is used to avoid special characters since
-        ultimately this will be used by NGINX.
-      - The `preview-` prefix is added to avoid conflicts if there's a remote branch
-        with the same name that you created in the merge request.
-      - The final branch name is truncated to 42 characters to avoid filesystem
-        limitations with long branch names (> 63 chars).
+   1. Forms the `gitlab-docs` branch name by applying the following:
+      - The `docs-preview-` prefix is added.
+      - The product slug is used to know the project the review app originated
+        from.
+      - The number of the merge request is added so that you can know by the
+        `gitlab-docs` branch name the merge requests it originated from.
    1. The remote branch is then created if it doesn't exist (meaning you can
       re-run the manual job as many times as you want and this step will be skipped).
    1. A new cross-project pipeline is triggered in the docs project.
@@ -503,6 +498,7 @@ The following GitLab features are used among others:
 - [Review Apps](../../ci/review_apps/index.md)
 - [Artifacts](../../ci/yaml/README.md#artifacts)
 - [Specific Runner](../../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects)
+- [Pipelines for merge requests](../../ci/merge_request_pipelines/index.md)
 
 ## Testing
 
diff --git a/scripts/trigger-build-docs b/scripts/trigger-build-docs
index dfc8ee6050a..5c55fd3ee31 100755
--- a/scripts/trigger-build-docs
+++ b/scripts/trigger-build-docs
@@ -16,14 +16,12 @@ end
 GITLAB_DOCS_REPO = 'gitlab-com/gitlab-docs'.freeze
 
 #
-# Truncate the remote docs branch name otherwise we hit the filesystem
-# limit and the directory name where NGINX serves the site won't match
-# the branch name.
+# This is the branch that will be created in the gitlab-docs project.
+# Name it after the product we're previewing and the ID of the MR that
+# kicked the review app.
 #
 def docs_branch
-  # The maximum string length a file can have on a filesystem (ext4)
-  # is 63 characters. CI_ENVIRONMENT_SLUG is limited to 24 characters.
-  ENV["CI_ENVIRONMENT_SLUG"]
+  "docs-preview-#{slug}-#{ENV["CI_MERGE_REQUEST_IID"]}"
 end
 
 #