Merge branch 'docs-merge-pipelines-ctrt-1' into 'master'

CTRT revamp for the MR pipelines doc

See merge request gitlab-org/gitlab!76723

app/views/projects/_merge_request_merge_checks_settings.html.haml

@@ -8,7 +8,7 @@
     = form.label :only_allow_merge_if_pipeline_succeeds, class: 'form-check-label' do
       = s_('ProjectSettings|Pipelines must succeed')
       .text-secondary
-        - configuring_pipelines_for_merge_requests_help_link_url = help_page_path('ci/pipelines/merge_request_pipelines.md', anchor: 'configure-pipelines-for-merge-requests')
+        - configuring_pipelines_for_merge_requests_help_link_url = help_page_path('ci/pipelines/merge_request_pipelines.md', anchor: 'prerequisites')
         - configuring_pipelines_for_merge_requests_help_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: configuring_pipelines_for_merge_requests_help_link_url }
         = s_('ProjectSettings|To enable this feature, configure pipelines. %{link_start}How to configure pipelines for merge requests?%{link_end}').html_safe % { link_start: configuring_pipelines_for_merge_requests_help_link_start, link_end: '</a>'.html_safe }
   .form-check.mb-2

doc/ci/pipelines/merge_request_pipelines.md

@@ -4,210 +4,195 @@ group: Pipeline Execution
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Pipelines for merge requests **(FREE)**
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/15310) in GitLab 11.6.
 
-In a [basic configuration](pipeline_architectures.md#basic-pipelines), GitLab runs a pipeline each time
-changes are pushed to a branch.
+# Pipelines for merge requests **(FREE)**
 
-If you want the pipeline to run jobs **only** on commits associated with a merge request,
-you can use *pipelines for merge requests*.
+You can configure your [pipeline](index.md) to run every time you commit changes to a branch.
+This type of pipeline is called a *branch pipeline*.
 
-These pipelines are labeled as `detached` in the UI, and they do not have access to [protected variables](../variables/index.md#protect-a-cicd-variable).
-Otherwise, these pipelines are the same as other pipelines.
+Alternatively, you can configure your pipeline to run every time you make changes to the
+source branch for a merge request. This type of pipeline is called a *pipeline for merge requests*.
 
-Pipelines for merge requests can run when you:
+Branch pipelines:
 
-- Create a new merge request.
-- Commit changes to the source branch for the merge request.
-- Select the **Run pipeline** button from the **Pipelines** tab in the merge request.
+- Run when you push a new commit to a branch.
+- Are the default type of pipeline.
+- Have access to [some predefined variables](../variables/predefined_variables.md).
+- Have access to [protected variables](../variables/index.md#protect-a-cicd-variable).
 
-If you use this feature with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md),
-pipelines for merge requests take precedence over other pipelines.
+Pipelines for merge requests:
 
-## Prerequisites
+- Run when you:
+  - Create a new merge request.
+  - Push a new commit to the source branch for a merge request.
+  - Select **Run pipeline** from the **Pipelines** tab in a merge request. This option
+    is only available when pipelines for merge requests are configured for the pipeline.
+- Do not run by default. The jobs in the CI/CD configuration file [must be configured](#prerequisites)
+  to run in pipelines for merge request.
+- Have access to [more predefined variables](#available-predefined-variables).
+- Do not have access to [protected variables](../variables/index.md#protect-a-cicd-variable).
 
-To enable pipelines for merge requests:
+Both of these types of pipelines can appear on the **Pipelines** tab of a merge request.
 
-- Your repository must be a GitLab repository, not an
-  [external repository](../ci_cd_for_external_repos/index.md).
-- You must have the Developer [role](../../user/permissions.md)
-  to run a pipeline for merge requests.
+## Types of pipelines for merge requests
 
-## Configure pipelines for merge requests
+The three types of pipelines for merge requests are:
 
-To configure pipelines for merge requests, you must configure your [CI/CD configuration file](../yaml/index.md).
-To do this, you can use [`rules`](#use-rules-to-run-pipelines-for-merge-requests) or [`only/except`](#use-only-or-except-to-run-pipelines-for-merge-requests).
+- Pipelines for merge requests, which run on the changes in the merge request's
+  source branch. These pipelines display a `detached` label to indicate that the
+  pipeline ran only on the contents of the source branch, ignoring the target branch.
+- [Pipelines for merged results](pipelines_for_merged_results.md), which run on
+  the result of combining the source branch's changes with the target branch.
+- [Merge trains](merge_trains.md), which run when merging multiple merge requests
+  at the same time. The changes from each merge request are combined into the
+  target branch with the changes in the earlier enqueued merge requests, to ensure
+  they all work together.
 
-### Use `rules` to run pipelines for merge requests
+## Prerequisites
 
-GitLab recommends that you use the `rules` keyword, which is available in
-[`workflow:rules` templates](../yaml/workflow.md#workflowrules-templates).
+To use pipelines for merge requests:
 
-### Use `only` or `except` to run pipelines for merge requests
+- Your project's [CI/CD configuration file](../yaml/index.md) must be configured with
+  jobs that run in pipelines for merge requests. To do this, you can use:
+  - [`rules`](#use-rules-to-add-jobs).
+  - [`only/except`](#use-only-to-add-jobs).
+- You must have at least the Developer [role](../../user/permissions.md) in the
+  source project to run a pipeline for merge requests.
+- Your repository must be a GitLab repository, not an [external repository](../ci_cd_for_external_repos/index.md).
 
-You can use the `only/except` keywords. However, with this method, you must specify `only: - merge_requests` for each job.
+## Use `rules` to add jobs
 
-In the following example, the pipeline contains a `test` job that is configured to run on merge requests.
-The `build` and `deploy` jobs don't have the `only: - merge_requests` keyword,
-so they don't run on merge requests.
+You can use the [`rules`](../yaml/index.md#rules) keyword to configure jobs to run in
+pipelines for merge requests. For example:
 
 ```yaml
-build:
-  stage: build
-  script: ./build
-  only:
-    - main
-
-test:
-  stage: test
-  script: ./test
-  only:
-    - merge_requests
-
-deploy:
-  stage: deploy
-  script: ./deploy
-  only:
-    - main
+job1:
+  script:
+    - echo "This job runs in pipelines for merge requests"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
 ```
 
-#### Exclude specific jobs
-
-When you use `only: [merge_requests]`, only jobs with
-that keyword are run in the context of a merge request. No other jobs run.
-
-However, you can invert this behavior and have all of your jobs run except
-for one or two. For example, you might have a pipeline with jobs `A`, `B`, and `C`, and you want:
-
-- All pipelines to always run `A` and `B`.
-- `C` to run only for merge requests.
-
-To achieve this outcome, configure your `.gitlab-ci.yml` file as follows:
+You can also use the [`workflow: rules`](../yaml/index.md#workflowrules) keyword
+to configure the entire pipeline to run in pipelines for merge requests. For example:
 
 ```yaml
-.only-default: &only-default
-  only:
-    - main
-    - merge_requests
-    - tags
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
 
-A:
-  <<: *only-default
+job1:
   script:
-    - ...
+    - echo "This job runs in pipelines for merge requests"
 
-B:
-  <<: *only-default
+job2:
   script:
-    - ...
-
-C:
-  script:
-    - ...
-  only:
-    - merge_requests
+    - echo "This job also runs in pipelines for merge requests"
 ```
 
-- `A` and `B` always run, because they get the `only` rule to execute in all cases.
-- `C` only runs for merge requests. It doesn't run for any pipeline
-  except a merge request pipeline.
-
-In this example, you don't have to add the `only` rule to all of your jobs to make
-them always run. You can use this format to set up a Review App, which helps to
-save resources.
+## Use `only` to add jobs
 
-#### Exclude specific branches
-
-Branch refs use this format: `refs/heads/my-feature-branch`.
-Merge request refs use this format: `refs/merge-requests/:iid/head`.
-
-Because of this difference, the following configuration does not work as expected:
-
-```yaml
-# Does not exclude a branch named "docs-my-fix"!
-test:
-  only: [merge_requests]
-  except: [/^docs-/]
-```
-
-Instead, use the
-[`$CI_COMMIT_REF_NAME` predefined environment
-variable](../variables/predefined_variables.md) in
-combination with
-[`only:variables`](../yaml/index.md#onlyvariables--exceptvariables) to
-accomplish this behavior:
+You can use the [`only`](../yaml/index.md#onlyrefs--exceptrefs) keyword with `merge_requests`
+to configure jobs to run in pipelines for merge requests.
 
 ```yaml
-test:
-  only: [merge_requests]
-  except:
-    variables:
-      - $CI_COMMIT_REF_NAME =~ /^docs-/
+job1:
+  script:
+    - echo "This job runs in pipelines for merge requests"
+  only:
+    - merge_requests
 ```
 
-## Run pipelines in the parent project for merge requests from a forked project **(PREMIUM)**
+## Use with forked projects
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217451) in GitLab 13.3.
 > - [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9.
 
-By default, external contributors who work in forks can't create pipelines in the
-parent project. When a merge request that comes from a fork triggers a pipeline:
+External contributors who work in forks can't create pipelines in the parent project.
 
-- The pipeline is created and runs in the fork (source) project, not the parent (target) project.
-- The pipeline uses the fork project's CI/CD configuration and resources.
+A merge request from a fork that is submitted to the parent project triggers a
+pipeline that:
 
-If a pipeline runs in a fork, a **fork** badge appears for the pipeline in the merge request.
+- Is created and runs in the fork (source) project, not the parent (target) project.
+- Uses the fork project's CI/CD configuration, resources, and project CI/CD variables.
 
-![Pipeline ran in fork](img/pipeline-fork_v13_7.png)
+Pipelines for forks display with the **fork** badge in the parent project:
 
-Sometimes parent project members want the pipeline to run in the parent
-project. They may want to ensure that the post-merge pipeline passes in the parent project.
-For example, a fork project could try to use a corrupted runner that doesn't execute
-test scripts properly, but reports a passed pipeline. Reviewers in the parent project
-could mistakenly trust the merge request because it passed a faked pipeline.
+![Pipeline ran in fork](img/pipeline_fork_v13_7.png)
 
-Parent project members with at least the [Developer role](../../user/permissions.md)
-can create pipelines in the parent project for merge requests
-from a forked project. In the merge request, go to the **Pipelines** tab and select
-**Run pipeline**.
+### Run pipelines in the parent project **(PREMIUM)**
+
+Project members in the parent project can choose to run a pipeline for merge requests
+for a merge request submitted from a fork project. This pipeline:
+
+- Is created and runs in the parent (target) project, not the fork (source) project.
+- Uses the CI/CD configuration present in the fork project's branch
+- Uses the parent project's CI/CD configuration, resources, and project CI/CD variables.
+- Uses the permissions of the parent project member that triggers the pipeline.
+
+Run pipelines in fork project MRs to ensure that the post-merge pipeline passes in
+the parent project. Additionally, if you do not trust the fork project's runner,
+running the pipeline in the parent project uses the parent project's trusted runners.
 
 WARNING:
 Fork merge requests can contain malicious code that tries to steal secrets in the
-parent project when the pipeline runs, even before merge. As a reviewer, you must carefully
+parent project when the pipeline runs, even before merge. As a reviewer, carefully
 check the changes in the merge request before triggering the pipeline. GitLab shows
 a warning that you must accept before you can trigger the pipeline.
 
-## Predefined variables available for pipelines for merge requests
+Parent project members with at least the [Developer role](../../user/permissions.md)
+can create pipelines in the parent project for merge requests from a forked project:
 
-When you use pipelines for merge requests, [additional predefined variables](../variables/predefined_variables.md#predefined-variables-for-merge-request-pipelines) are available to the CI/CD jobs.
-These variables contain information from the associated merge request, so that you can
-integrate your job with the [GitLab Merge Request API](../../api/merge_requests.md).
+1. In the merge request, go to the **Pipelines** tab.
+1. Select **Run pipeline**. You must accept the warning, or the pipeline does not run.
 
-## Troubleshooting
+## Available predefined variables
 
-### Two pipelines created when pushing to a merge request
+When you use pipelines for merge requests, you can use:
+
+- All the same [predefined variables](../variables/predefined_variables.md) that are
+  available in branch pipelines.
+- [Additional predefined variables](../variables/predefined_variables.md#predefined-variables-for-merge-request-pipelines)
+  available only to jobs in pipelines for merge requests. These variables contain
+  information from the associated merge request, which can be when calling the
+  [GitLab Merge Request API endpoint](../../api/merge_requests.md) from a job.
+
+## Troubleshooting
 
-If you are experiencing duplicated pipelines when using `rules`, take a look at
-the [important differences between `rules` and `only`/`except`](../jobs/job_control.md#avoid-duplicate-pipelines),
-which helps you get your starting configuration correct.
+### Two pipelines when pushing to a branch
 
-If you are seeing two pipelines when using `only/except`, please see the caveats
-related to using `only/except` above (or, consider moving to `rules`).
+If you get duplicate pipelines in merge requests, your pipeline might be configured
+to run for both branches and merge requests at the same time. Adjust your pipeline
+configuration to [avoid duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines).
 
 In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201845),
-you can add `workflow:rules` to [switch from branch pipelines to merge request pipelines](../yaml/workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines).
+you can add `workflow:rules` to [switch from branch pipelines to pipelines for merge requests](../yaml/workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines).
 After a merge request is open on the branch, the pipeline switches to a merge request pipeline.
 
-### Two pipelines created when pushing an invalid CI configuration file
+### Two pipelines when pushing an invalid CI/CD configuration file
+
+If you push an invalid CI/CD configuration to a merge request's branch, two failed
+pipelines appear in the pipelines tab. One pipeline is a failed branch pipeline,
+the other is a failed pipeline for merge requests.
+
+When the configuration syntax is fixed, no further failed pipelines should appear.
+To find and fix the configuration problem, you can use:
+
+- The [pipeline editor](../pipeline_editor/index.md).
+- The [CI lint tool](../lint.md).
+
+### The merge request's pipeline is marked as failed but the latest pipeline succeeded
+
+It's possible to have both branch pipelines and pipelines for merge requests in the
+**Pipelines** tab of a single merge request. This might be [by configuration](../yaml/workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines),
+or [by accident](#two-pipelines-when-pushing-to-a-branch).
 
-Pushing to a branch with an invalid CI configuration file can trigger
-the creation of two types of failed pipelines. One pipeline is a failed merge request
-pipeline, and the other is a failed branch pipeline, but both are caused by the same
-invalid configuration.
+If both types of pipelines are in one merge request, the merge request's pipeline
+is not considered successful if:
 
-## Related topics
+- The branch pipeline succeeds.
+- The pipeline for merge request fails.
 
-- [Pipelines for merged results](pipelines_for_merged_results.md).
-- [Merge trains](merge_trains.md).
+When using the [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md)
+feature and both pipelines types are present, the pipelines for merge requests are checked,
+not the branch pipelines.

doc/ci/pipelines/merge_trains.md

@@ -78,7 +78,7 @@ To enable merge trains:
 To enable merge trains for your project:
 
 1. If you are on a self-managed GitLab instance, ensure the [feature flag](#merge-trains-feature-flag) is set correctly.
-1. [Configure your CI/CD configuration file](merge_request_pipelines.md#configure-pipelines-for-merge-requests)
+1. [Configure your CI/CD configuration file](merge_request_pipelines.md#prerequisites)
    so that the pipeline or individual jobs run for merge requests.
 1. On the top bar, select **Menu > Projects** and find your project.
 1. On the left sidebar, select **Settings > General**.

doc/ci/pipelines/pipelines_for_merged_results.md

@@ -55,7 +55,7 @@ To enable pipelines for merge results:
 
 To enable pipelines for merged results for your project:
 
-1. [Configure your CI/CD configuration file](merge_request_pipelines.md#configure-pipelines-for-merge-requests)
+1. [Configure your CI/CD configuration file](merge_request_pipelines.md#prerequisites)
    so that the pipeline or individual jobs run for merge requests.
 1. Visit your project's **Settings > General** and expand **Merge requests**.
 1. Check **Enable merged results pipelines**.

doc/ci/variables/index.md

@@ -81,7 +81,7 @@ to execute scripts. Each shell has its own set of reserved variable names.
 Make sure each variable is defined for the [scope you want to use it in](where_variables_can_be_used.md).
 
 By default, pipelines from forked projects can't access CI/CD variables in the parent project.
-If you [run a merge request pipeline in the parent project for a merge request from a fork](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project),
+If you [run a merge request pipeline in the parent project for a merge request from a fork](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project),
 all variables become available to the pipeline.
 
 ### Create a custom CI/CD variable in the `.gitlab-ci.yml` file
@@ -394,7 +394,7 @@ runs on a [protected branch](../../user/project/protected_branches.md) or
 
 Review all merge requests that introduce changes to the `.gitlab-ci.yml` file before you:
 
-- [Run a pipeline in the parent project for a merge request submitted from a forked project](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project).
+- [Run a pipeline in the parent project for a merge request submitted from a forked project](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project).
 - Merge the changes.
 
 The following example shows malicious code in a `.gitlab-ci.yml` file:

doc/ci/yaml/index.md

@@ -415,6 +415,7 @@ and the pipeline is for either:
 - You can use the [`workflow:rules` templates](workflow.md#workflowrules-templates) to import
   a preconfigured `workflow: rules` entry.
 - [Common `if` clauses for `workflow:rules`](workflow.md#common-if-clauses-for-workflowrules).
+- [Use `rules` to run pipelines for merge requests](../pipelines/merge_request_pipelines.md#use-rules-to-add-jobs).
 
 #### `workflow:rules:variables`
 
@@ -3079,6 +3080,7 @@ job:
 
 - [Common `if` expressions for `rules`](../jobs/job_control.md#common-if-clauses-for-rules).
 - [Avoid duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines).
+- [Use `rules` to run pipelines for merge requests](../pipelines/merge_request_pipelines.md#use-rules-to-add-jobs).
 
 #### `rules:changes`
 

doc/development/code_review.md

@@ -501,7 +501,7 @@ Merge Results against the latest `main` at the time of the pipeline creation.
 
 WARNING:
 **Review all changes thoroughly for malicious code before starting a
-[Pipeline for Merged Results](../ci/pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project).**
+[Pipeline for Merged Results](../ci/pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project).**
 
 When reviewing merge requests added by wider community contributors:
 

doc/subscriptions/bronze_starter.md

@@ -98,7 +98,7 @@ the tiers are no longer mentioned in GitLab documentation:
     - [Bidirectional mirroring](../user/project/repository/mirror/bidirectional.md)
     - [Mirror with Perforce Helix with Git Fusion](../user/project/repository/mirror/bidirectional.md#mirror-with-perforce-helix-with-git-fusion)
 - Runners:
-  - Run pipelines in the parent project [for merge requests from a forked project](../ci/pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project)
+  - Run pipelines in the parent project [for merge requests from a forked project](../ci/pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project)
   - [Shared runners CI/CD minutes](../ci/pipelines/cicd_minutes.md)
 - [Push rules](../push_rules/push_rules.md)
 - SAML for self-managed GitLab instance:

doc/user/project/merge_requests/fail_fast_testing.md

@@ -42,7 +42,7 @@ This template requires:
 - A project built in Rails that uses RSpec for testing.
 - CI/CD configured to:
   - Use a Docker image with Ruby available.
-  - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#configure-pipelines-for-merge-requests)
+  - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#prerequisites)
 - [Pipelines for Merged Results](../../../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results)
   enabled in the project settings.
 - A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#override-included-configuration-values) this.

ee/app/views/projects/_merge_pipelines_settings.html.haml

@@ -5,6 +5,6 @@
   = form.label :merge_pipelines_enabled, class: 'form-check-label' do
     = s_('ProjectSettings|Enable merged results pipelines')
     .text-secondary.mb-2
-      - configuring_pipelines_for_merge_requests_help_link_url = help_page_path('ci/pipelines/merge_request_pipelines.md', anchor: 'configure-pipelines-for-merge-requests')
+      - configuring_pipelines_for_merge_requests_help_link_url = help_page_path('ci/pipelines/merge_request_pipelines.md', anchor: 'prerequisites')
       - configuring_pipelines_for_merge_requests_help_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: configuring_pipelines_for_merge_requests_help_link_url }
       = s_('ProjectSettings|When pipelines for merge requests are enabled in the CI/CD configuration file, pipelines validate the combined results of the source and target branches. %{link_start}How to configure pipelines for merge requests?%{link_end}').html_safe % { link_start: configuring_pipelines_for_merge_requests_help_link_start, link_end: '</a>'.html_safe }