diff --git a/doc/ci/debugging.md b/doc/ci/debugging.md index 35d3891393349330b9a71342142e0e4896235b80..ee99716e49918b1efffba4f65da4776855c1154e 100644 --- a/doc/ci/debugging.md +++ b/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). diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index 0cefd579892f6774545169fb7fe81895e22be554..6c888c43b5d296c6bb6a1373e987233320acf2d0 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/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. diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md index 3e3a54dbf543151368ab99dba7d410852b3de339..a06813365c92e682fe8330dfb9de8b2c5df7a7cf 100644 --- a/doc/ci/pipelines/merge_trains.md +++ b/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: diff --git a/doc/ci/pipelines/merged_results_pipelines.md b/doc/ci/pipelines/merged_results_pipelines.md index 28bfcb2160374b25910b166d29441909f885c8b4..414c5a5caae2b8c1f34c19b678a40538454890e5 100644 --- a/doc/ci/pipelines/merged_results_pipelines.md +++ b/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 diff --git a/doc/ci/pipelines/mr_pipeline_troubleshooting.md b/doc/ci/pipelines/mr_pipeline_troubleshooting.md new file mode 100644 index 0000000000000000000000000000000000000000..4fa5bcd1aa09161d364a6dc80fe25fa0a4226cc5 --- /dev/null +++ b/doc/ci/pipelines/mr_pipeline_troubleshooting.md @@ -0,0 +1,98 @@ +--- +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. diff --git a/doc/ci/pipelines/pipeline_types.md b/doc/ci/pipelines/pipeline_types.md new file mode 100644 index 0000000000000000000000000000000000000000..a8b3080070d86c534ed3852c4237c3fd68a0dc99 --- /dev/null +++ b/doc/ci/pipelines/pipeline_types.md @@ -0,0 +1,80 @@ +--- +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).