diff options
Diffstat (limited to 'doc/user/project/merge_requests/merge_when_pipeline_succeeds.md')
| -rw-r--r-- | doc/user/project/merge_requests/merge_when_pipeline_succeeds.md | 87 |
1 files changed, 50 insertions, 37 deletions
diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index d45ccdc9be9..7d90c9f3cd7 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -1,36 +1,38 @@ --- +stage: Create +group: Source Code +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/#designated-technical-writers type: reference, concepts --- # Merge when pipeline succeeds -When reviewing a merge request that looks ready to merge but still has one or -more CI jobs running, you can set it to be merged automatically when the -jobs pipeline succeeds. This way, you don't have to wait for the jobs to +When reviewing a merge request that looks ready to merge but still has a +pipeline running, you can set it to merge automatically when the +pipeline succeeds. This way, you don't have to wait for the pipeline to finish and remember to merge the request manually.  ## How it works -When you hit the "Merge When Pipeline Succeeds" button, the status of the merge -request will be updated to represent the impending merge. If you cannot wait -for the pipeline to succeed and want to merge immediately, this option is -available in the dropdown menu on the right of the main button. +When you click "Merge When Pipeline Succeeds", the status of the merge +request is updated to show the impending merge. If you can't wait +for the pipeline to succeed, you can choose **Merge immediately** +in the dropdown menu on the right of the main button. -Both team developers and the author of the merge request have the option to -cancel the automatic merge if they find a reason why it shouldn't be merged -after all. +The author of the merge request and project members with developer permissions can +cancel the automatic merge at any time before the pipeline finishes.  -When the pipeline succeeds, the merge request will automatically be merged. +When the pipeline succeeds, the merge request is automatically merged. When the pipeline fails, the author gets a chance to retry any failed jobs, or to push new commits to fix the failure. When the jobs are retried and succeed on the second try, the merge request -will automatically be merged after all. When the merge request is updated with -new commits, the automatic merge is automatically canceled to allow the new +is automatically merged. When the merge request is updated with +new commits, the automatic merge is canceled to allow the new changes to be reviewed. ## Only allow merge requests to be merged if the pipeline succeeds @@ -42,7 +44,7 @@ or if there are threads to be resolved. This works for both: - Pipelines run from an [external CI integration](../integrations/overview.md#integrations-listing) As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci.md) -will not disable this feature, as it will still be possible to use pipelines from external +does not disable this feature, as it is possible to use pipelines from external CI providers with this feature. To enable it, you must: 1. Navigate to your project's **Settings > General** page. @@ -50,14 +52,40 @@ CI providers with this feature. To enable it, you must: 1. In the **Merge checks** subsection, select the **Pipelines must succeed** checkbox. 1. Press **Save** for the changes to take effect. -NOTE: **Note:** This setting also prevents merge requests from being merged if there is no pipeline. +This setting also prevents merge requests from being merged if there is no pipeline. - +### Limitations + +When this setting is enabled, a merge request is prevented from being merged if there +is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#onlyexcept-advanced) +or [`rules`](../../../ci/yaml/README.md#rules) are used and they don't generate any pipelines. + +You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) +and that it's successful. + +If both a branch pipeline and a merge request pipeline are triggered for a single +merge request, only the success or failure of the *merge request pipeline* is checked. +If the merge request pipeline is configured with fewer jobs than the branch pipeline, +it could allow code that fails tests to be merged: + +```yaml +branch-pipeline-job: + rules: + - if: '$CI_PIPELINE_SOURCE == "push"' + script: + - echo "Code testing scripts here, for example." -From now on, every time the pipeline fails you will not be able to merge the -merge request from the UI, until you make all relevant jobs pass. +merge-request-pipeline-job: + rules: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + script: + - echo "No tests run, but this pipeline always succeeds and enables merge." + - echo true +``` - +You should avoid configuration like this, and only use branch (`push`) pipelines +or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#differences-between-rules-and-onlyexcept) +for details on avoiding two pipelines for a single merge request. ### Skipped pipelines @@ -72,20 +100,10 @@ merge requests from being merged. To change this behavior: 1. In the **Merge checks** subsection, select the **Skipped pipelines are considered successful** checkbox. 1. Press **Save** for the changes to take effect. -### Limitations - -When this setting is enabled, a merge request is prevented from being merged if there is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#onlyexcept-advanced) rules are used and they don't generate any pipelines. - -Users that expect to be able to merge a merge request in this scenario should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) and that it's successful. +## From the command line -For example, to that on merge requests there is always a passing job even though `only/except` rules may not generate any other jobs: - -```yaml -enable_merge: - only: [merge_requests] - script: - - echo true -``` +You can use [Push Options](../push_options.md) to enable merge when pipeline succeeds +for a merge request when pushing from the command line. <!-- ## Troubleshooting @@ -98,8 +116,3 @@ questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> - -## Use it from the command line - -You can use [Push Options](../push_options.md) to trigger this feature when -pushing. |