Clarifying pipeline types

Because people would like to
compare them

doc/ci/debugging.md

@@ -175,7 +175,7 @@ For help with a specific area, see:
 - [Jobs](jobs/index.md#troubleshooting).
 - [Job control](jobs/job_control.md).
 - [Job artifacts](jobs/job_artifacts_troubleshooting.md).
-- [Merge request pipelines](pipelines/merge_request_pipelines.md#troubleshooting),
+- [Merge request pipelines](pipelines/mr_pipeline_troubleshooting.md),
   [merged results pipelines](pipelines/merged_results_pipelines.md#troubleshooting),
   and [Merge trains](pipelines/merge_trains.md#troubleshooting).
 - [Pipeline editor](pipeline_editor/index.md#troubleshooting).

doc/ci/pipelines/merge_request_pipelines.md

@@ -4,7 +4,6 @@ group: Pipeline Execution
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-
 # Merge request pipelines
 
 DETAILS:
@@ -13,50 +12,26 @@ DETAILS:
 
 > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/351192) from `pipelines for merge requests` to `merge request pipelines` in GitLab 14.8.
 
-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*.
-
-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 *merge request pipeline*.
-
-Branch pipelines:
-
-- 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) and [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information).
-
-Merge request pipelines:
+You can configure your pipeline to run every time you make changes to the
+source branch in a merge request.
 
-- **Do not run by default**. The jobs in the CI/CD configuration file [must be configured](#prerequisites)
-  to run in merge request pipelines. Some configurations can [accidentally cause merge request pipelines to run](#two-pipelines-when-pushing-to-a-branch).
-- If configured, merge request pipelines run when you:
-  - Create a new merge request from a source branch with one or more commits.
-  - 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 merge request pipelines are configured for the pipeline
-    and the source branch has at least one commit.
-- Have access to [more predefined variables](#available-predefined-variables).
-- Do not have access to [protected variables](../variables/index.md#protect-a-cicd-variable) or [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information).
+This type of pipeline, called a merge request pipeline, runs when you:
 
-Both of these types of pipelines can appear on the **Pipelines** tab of a merge request.
+- Create a new merge request from a source branch that has one or more commits.
+- Push a new commit to the source branch for a merge request.
+- Go to the **Pipelines** tab in a merge request and select **Run pipeline**.
 
-## Types of merge request pipelines
+In addition, merge request pipelines:
 
-> - The `detached` label was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352939) to `merge request` in GitLab 14.9.
-> - The `merged results` label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132975) in GitLab 16.5.
+- Have access to [more predefined variables](merge_request_pipelines.md#available-predefined-variables).
+- Do not have access to [protected variables](../variables/index.md#protect-a-cicd-variable) or
+  [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information).
 
-The three types of merge request pipelines are:
+These pipelines display a `merge request` label in pipeline lists.
 
-- Merge request pipelines, which run on the changes in the merge request's
-  source branch, ignoring the target branch. These pipelines display a `merge request` label in pipeline lists.
-- [Merged results pipelines](merged_results_pipelines.md), which run on
-  the result of combining the source branch's changes with the target branch.
-  These pipelines display a `merged results` label in pipeline lists.
-- [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. These pipelines display a `merge train` label in pipeline lists.
+Merge request pipelines run on the contents of the source branch only, ignoring the content
+of the target branch. To run a pipeline that tests the result of merging the source
+and target branches together, use merged results pipelines.
 
 ## Prerequisites
 
@@ -198,94 +173,3 @@ When you use merge request pipelines, you can use:
   available in branch pipelines.
 - [Additional predefined variables](../variables/predefined_variables.md#predefined-variables-for-merge-request-pipelines)
   available only to jobs in merge request pipelines.
-
-## Troubleshooting
-
-### Two pipelines when pushing to a branch
-
-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).
-After a merge request is open on the branch, the pipeline switches to a merge request pipeline.
-
-### 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 merge request pipeline.
-
-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 merge request pipelines 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).
-
-When the project has [**Pipelines must succeed**](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#require-a-successful-pipeline-for-merge) enabled
-and both pipelines types are present, the merge request pipelines are checked,
-not the branch pipelines.
-
-Therefore, the MR pipeline result is marked as unsuccessful if the
-**merge request pipeline** fails, independently of the **branch pipeline** result.
-
-However:
-
-- These conditions are not enforced.
-- A race condition determines which pipeline's result is used to either block or pass merge requests.
-
-This bug is tracked on [issue 384927](https://gitlab.com/gitlab-org/gitlab/-/issues/384927).
-
-### `An error occurred while trying to run a new pipeline for this merge request.`
-
-This error can happen when you select **Run pipeline** in a merge request, but the
-project does not have merge request pipelines enabled anymore.
-
-Some possible reasons for this error message:
-
-- The project does not have merge request pipelines enabled, has no pipelines listed
-  in the **Pipelines** tab, and you select **Run pipelines**.
-- The project used to have merge request pipelines enabled, but the configuration
-  was removed. For example:
-
-  1. The project has merge request pipelines enabled in the `.gitlab-ci.yml` configuration
-     file when the merge request is created.
-  1. The **Run pipeline** options is available in the merge request's **Pipelines** tab,
-     and selecting **Run pipeline** at this point likely does not cause any errors.
-  1. The project's `.gitlab-ci.yml` file is changed to remove the merge request pipelines configuration.
-  1. The branch is rebased to bring the updated configuration into the merge request.
-  1. Now the pipeline configuration no longer supports merge request pipelines,
-     but you select **Run pipeline** to run a merge request pipeline.
-
-If **Run pipeline** is available, but the project does not have merge request pipelines
-enabled, do not use this option. You can push a commit or rebase the branch to trigger
-new branch pipelines.
-
-### `Merge blocked: pipeline must succeed. Push a new commit that fixes the failure` message
-
-This message is shown if the merge request pipeline, [merged results pipeline](merged_results_pipelines.md),
-or [merge train pipeline](merge_trains.md) has failed or been canceled.
-This does not happen when a branch pipeline fails.
-
-If a merge request pipeline or merged result pipeline was canceled or failed, you can:
-
-- Re-run the entire pipeline by selecting **Run pipeline** in the pipeline tab in the merge request.
-- [Retry only the jobs that failed](index.md#view-pipelines). If you re-run the entire pipeline, this is not necessary.
-- Push a new commit to fix the failure.
-
-If the merge train pipeline has failed, you can:
-
-- Check the failure and determine if you can use the [`/merge` quick action](../../user/project/quick_actions.md) to immediately add the merge request to the train again.
-- Re-run the entire pipeline by selecting **Run pipeline** in the pipeline tab in the merge request, then add the merge request to the train again.
-- Push a commit to fix the failure, then add the merge request to the train again.
-
-If the merge train pipeline was canceled before the merge request was merged, without a failure, you can:
-
-- Add it to the train again.

doc/ci/pipelines/merge_trains.md

@@ -10,20 +10,12 @@ DETAILS:
 **Tier:** Premium, Ultimate
 **Offering:** SaaS, self-managed
 
-> Support for [fast-forward](../../user/project/merge_requests/methods/index.md#fast-forward-merge) and [semi-linear](../../user/project/merge_requests/methods/index.md#merge-commit-with-semi-linear-history) merge methods [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282442) in GitLab 16.5 [with a flag](../../administration/feature_flags.md) named `fast_forward_merge_trains_support`. Enabled by default.
-
-NOTE:
-[In GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/359057), the **Start merge train**
-and **Start merge train when pipeline succeeds** buttons became **Set to auto-merge**.
-**Remove from merge train** became **Cancel auto-merge**.
-
-Use merge trains to queue merge requests and verify their changes work together before
-they are merged to the target branch.
+> - [In GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/359057), the **Start merge train** and **Start merge train when pipeline succeeds** buttons became **Set to auto-merge**. **Remove from merge train** became **Cancel auto-merge**.
+> - Support for [fast-forward](../../user/project/merge_requests/methods/index.md#fast-forward-merge) and [semi-linear](../../user/project/merge_requests/methods/index.md#merge-commit-with-semi-linear-history) merge methods [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282442) in GitLab 16.5 [with a flag](../../administration/feature_flags.md) named `fast_forward_merge_trains_support`. Enabled by default.
 
 In projects with frequent merges to the default branch, changes in different merge requests
-might conflict with each other. [Merged results pipelines](merged_results_pipelines.md)
-ensure the changes work with the content in the default branch, but not content
-that others are merging at the same time.
+might conflict with each other. Use merge trains to put merge requests in a queue.
+Each merge request is compared to the other, earlier merge requests, to ensure they all work together.
 
 For more information about:
 

doc/ci/pipelines/merged_results_pipelines.md

@@ -13,7 +13,8 @@ DETAILS:
 > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/351192) from `pipelines for merged results` to `merged results pipelines` in GitLab 14.8.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91849) in GitLab 15.1, merged results pipelines also run on [Draft merge requests](../../user/project/merge_requests/drafts.md).
 
-A *merged results pipeline* is a type of [merge request pipeline](merge_request_pipelines.md). It is a pipeline that runs against the results of the source and target branches merged together.
+A merged results pipeline runs on the result of the source and target branches merged together.
+It is a type of [merge request pipeline](merge_request_pipelines.md).
 
 GitLab creates an internal commit with the merged results, so the pipeline can run
 against it. This commit does not exist in either branch,
@@ -26,7 +27,7 @@ Any time you want to be sure the merged results are accurate, you should re-run
 
 Merged results pipelines can't run when the target branch has changes that conflict with the changes in the source branch.
 In these cases, the pipeline runs as a [merge request pipeline](merge_request_pipelines.md)
-and [is labeled as `merge request`](merge_request_pipelines.md#types-of-merge-request-pipelines).
+and is labeled as `merge request`.
 
 ## Prerequisites
 

doc/ci/pipelines/mr_pipeline_troubleshooting.md

+---
+stage: Verify
+group: Pipeline Execution
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# Merge request pipeline troubleshooting
+
+When working with merge request pipelines, you might encounter the following issues.
+
+## Two pipelines when pushing to a branch
+
+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).
+After a merge request is open on the branch, the pipeline switches to a merge request pipeline.
+
+## 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 merge request pipeline.
+
+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 merge request pipelines 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).
+
+When the project has [**Pipelines must succeed**](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#require-a-successful-pipeline-for-merge) enabled
+and both pipelines types are present, the merge request pipelines are checked,
+not the branch pipelines.
+
+Therefore, the MR pipeline result is marked as unsuccessful if the
+**merge request pipeline** fails, independently of the **branch pipeline** result.
+
+However:
+
+- These conditions are not enforced.
+- A race condition determines which pipeline's result is used to either block or pass merge requests.
+
+This bug is tracked on [issue 384927](https://gitlab.com/gitlab-org/gitlab/-/issues/384927).
+
+## `An error occurred while trying to run a new pipeline for this merge request.`
+
+This error can happen when you select **Run pipeline** in a merge request, but the
+project does not have merge request pipelines enabled anymore.
+
+Some possible reasons for this error message:
+
+- The project does not have merge request pipelines enabled, has no pipelines listed
+  in the **Pipelines** tab, and you select **Run pipelines**.
+- The project used to have merge request pipelines enabled, but the configuration
+  was removed. For example:
+
+  1. The project has merge request pipelines enabled in the `.gitlab-ci.yml` configuration
+     file when the merge request is created.
+  1. The **Run pipeline** options is available in the merge request's **Pipelines** tab,
+     and selecting **Run pipeline** at this point likely does not cause any errors.
+  1. The project's `.gitlab-ci.yml` file is changed to remove the merge request pipelines configuration.
+  1. The branch is rebased to bring the updated configuration into the merge request.
+  1. Now the pipeline configuration no longer supports merge request pipelines,
+     but you select **Run pipeline** to run a merge request pipeline.
+
+If **Run pipeline** is available, but the project does not have merge request pipelines
+enabled, do not use this option. You can push a commit or rebase the branch to trigger
+new branch pipelines.
+
+## `Merge blocked: pipeline must succeed. Push a new commit that fixes the failure` message
+
+This message is shown if the merge request pipeline, [merged results pipeline](merged_results_pipelines.md),
+or [merge train pipeline](merge_trains.md) has failed or been canceled.
+This does not happen when a branch pipeline fails.
+
+If a merge request pipeline or merged result pipeline was canceled or failed, you can:
+
+- Re-run the entire pipeline by selecting **Run pipeline** in the pipeline tab in the merge request.
+- [Retry only the jobs that failed](index.md#view-pipelines). If you re-run the entire pipeline, this is not necessary.
+- Push a new commit to fix the failure.
+
+If the merge train pipeline has failed, you can:
+
+- Check the failure and determine if you can use the [`/merge` quick action](../../user/project/quick_actions.md) to immediately add the merge request to the train again.
+- Re-run the entire pipeline by selecting **Run pipeline** in the pipeline tab in the merge request, then add the merge request to the train again.
+- Push a commit to fix the failure, then add the merge request to the train again.
+
+If the merge train pipeline was canceled before the merge request was merged, without a failure, you can:
+
+- Add it to the train again.

doc/ci/pipelines/pipeline_types.md

+---
+stage: Verify
+group: Pipeline Execution
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# Types of pipelines
+
+DETAILS:
+**Tier:** Free, Premium, Ultimate
+**Offering:** SaaS, self-managed
+
+Four types of pipelines exist:
+
+- Branch pipelines
+- Merge request pipelines
+- Merge result pipelines
+- Merge trains
+
+These types of pipelines all appear on the **Pipelines** tab of a merge request.
+
+## Branch pipeline
+
+Your pipeline can run every time you commit changes to a branch.
+
+This type of pipeline is called a *branch pipeline*.
+
+This pipeline runs by default. No configuration is required.
+
+Branch pipelines:
+
+- Run when you push a new commit to a branch.
+- Have access to [some predefined variables](../variables/predefined_variables.md).
+- Have access to [protected variables](../variables/index.md#protect-a-cicd-variable)
+  and [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information).
+
+## Merge request pipeline
+
+> - The `detached` label was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352939) to `merge request` in GitLab 14.9.
+
+Instead of a branch pipeline, you can configure your pipeline to run every time you make changes to the
+source branch in a merge request.
+
+This type of pipeline is called a *merge request pipeline*.
+
+Merge request pipelines do not run by default. You must configure
+the jobs in the `.gitlab-ci.yml` file to run as merge request pipelines.
+
+For more information, see [merge request pipelines](merge_request_pipelines.md).
+
+## Merged results pipeline
+
+> - The `merged results` label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132975) in GitLab 16.5.
+
+A *merged results pipeline* runs on the result of the source and target branches merged together.
+It's a type of merge request pipeline.
+
+These pipelines do not run by default. You must configure the jobs in the `.gitlab-ci.yml` file
+to run as a merge request pipeline, and enable merge request pipelines.
+
+These pipelines display a `merged results` label in pipeline lists.
+
+For more information, see [merged results pipeline](merged_results_pipelines.md).
+
+## Merge trains
+
+In projects with frequent merges to the default branch, changes in different merge requests
+might conflict with each other. Use *merge trains* to put merge requests in a queue.
+Each merge request is compared to the other, earlier merge requests, to ensure they all work together.
+
+Merge trains differ from merged results pipelines, because merged results pipelines
+ensure the changes work with the content in the default branch,
+but not content that others are merging at the same time.
+
+These pipelines do not run by default. You must configure the jobs in the `.gitlab-ci.yml` file
+to run as a merge request pipeline, enable merge request pipelines, and enable merge trains.
+
+These pipelines display a `merge train` label in pipeline lists.
+
+For more information, see [merge trains](merge_trains.md).