Merge branch 'fix-review-docs-deploy-doc' into 'master'

doc: Clarify the 'review-docs-deploy' job documentation

See merge request gitlab-org/gitlab!58022

doc/development/documentation/index.md

@@ -218,7 +218,7 @@ To add a redirect:
 
    If you don't want to use the Rake task, you can use the following template.
    However, the file paths must be relative to the `doc` or `docs` directory.
-   
+
    Replace the value of `redirect_to` with the new file path and `YYYY-MM-DD`
    with the date the file should be removed.
 
@@ -421,8 +421,6 @@ The live preview is currently enabled for the following projects:
 
 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.
-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)
 
@@ -461,19 +459,11 @@ 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 merge request.
 1. The job runs the [`scripts/trigger-build`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/trigger-build)
-   script with the `docs deploy` flag, which in turn:
-   1. Takes your branch name and applies 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 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 is skipped).
-   1. A new cross-project pipeline is triggered in the docs project.
-   1. The preview URL is shown both at the job output and in the merge request
-      widget. You also get the link to the remote pipeline.
-1. In the docs project, the pipeline is created and it
+   script with the `docs deploy` flag, which triggers the "Triggered from `gitlab-org/gitlab` 'review-docs-deploy' job"
+   pipeline trigger in the `gitlab-org/gitlab-docs` project for the `$DOCS_BRANCH` (defaults to `master`).
+1. The preview URL is shown both at the job output and in the merge request
+   widget. You also get the link to the remote pipeline.
+1. In the `gitlab-org/gitlab-docs` project, the pipeline is created and it
    [skips the test jobs](https://gitlab.com/gitlab-org/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55)
    to lower the build time.
 1. Once the docs site is built, the HTML files are uploaded as artifacts.

doc/development/testing_guide/end_to_end/index.md

@@ -94,6 +94,19 @@ subgraph "`gitlab-org/gitlab-qa-mirror` pipeline"
 Please note, we plan to [add more specific information](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/156)
 about the tests included in each job/scenario that runs in `gitlab-org/gitlab-qa-mirror`.
 
+NOTE:
+You may have noticed that we use `gitlab-org/build/omnibus-gitlab-mirror` instead of
+`gitlab-org/omnibus-gitlab`, and `gitlab-org/gitlab-qa-mirror` instead of `gitlab-org/gitlab-qa`.
+This is due to technical limitations in the GitLab permission model: the ability to run a pipeline
+against a protected branch is controlled by the ability to push/merge to this branch.
+This means that for developers to be able to trigger a pipeline for the default branch in
+`gitlab-org/omnibus-gitlab`/`gitlab-org/gitlab-qa`, they would need to have Maintainer permission in those projects.
+For security reasons and implications, we couldn't open up the default branch to all the Developers.
+Hence we created these mirrors where Developers and Maintainers are allowed to push/merge to the default branch.
+This problem was discovered in <https://gitlab.com/gitlab-org/gitlab-qa/-/issues/63#note_107175160> and the "mirror"
+work-around was suggested in <https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4717>.
+A feature proposal to segregate access control regarding running pipelines from ability to push/merge was also created at <https://gitlab.com/gitlab-org/gitlab/-/issues/24585>.
+
 #### With Pipeline for Merged Results
 
 In a Pipeline for Merged Results, the pipeline runs on a new ref that contains the merge result of the source and target branch.