Use the MR IID in the docs Review Apps URLs

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.

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

@@ -14,10 +14,10 @@
   variables:
     GIT_STRATEGY: none
   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-foss/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
   before_script:
     # We don't clone the repo by using GIT_STRATEGY: none and only download the
@@ -39,7 +39,7 @@ review-docs-deploy:
 review-docs-cleanup:
   extends: .review-docs
   environment:
-    name: review-docs/$CI_COMMIT_REF_SLUG
+    name: review-docs/$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID
     action: stop
   script:
     - ./trigger-build-docs cleanup

doc/development/documentation/index.md

@@ -302,17 +302,17 @@ 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-org/gitlab-docs)
-   project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`,
-   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
-
-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:
-
-- In the merge request widget
-- In the output of the `review-docs-deploy*` job, which also includes the
-  triggered pipeline so that you can investigate whether something went wrong
+   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. Trigger 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
+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.
 
 TIP: **Tip:**
 Someone with no merge rights to the GitLab projects (think of forks from
@@ -345,12 +345,11 @@ If you want to know the in-depth details, here's what's really happening:
 1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab/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).
+      - 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 request 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.
@@ -371,6 +370,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
 

scripts/trigger-build-docs

@@ -16,14 +16,12 @@ end
 GITLAB_DOCS_REPO = 'gitlab-org/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
 
 #