Merge when pipeline succeeds

If you review a merge request and it’s ready to merge, but the pipeline hasn’t completed yet, you can set it to merge when the pipeline succeeds (MWPS). You don’t have to remember later to merge the work manually:

Enable MWPS on a merge request

If the pipeline succeeds, the merge request is merged. If the pipeline fails, the author can either retry any failed jobs, or push new commits to fix the failure:

  • If a retried job succeeds on the second try, the merge request is merged.
  • If new commits are added to the merge request, GitLab cancels the MWPS request to ensure the new changes are reviewed before merge.

Set a merge request to MWPS

Prerequisites:

  • You must have at least the Developer role in the project.
  • If the project is configured to require it, all threads in the merge request must be resolved.
  • The merge request must have received all required approvals.

To do this when pushing from the command line, use the merge_request.merge_when_pipeline_succeeds push option.

To do this from the GitLab user interface:

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Merge requests.
  3. Scroll to the merge request reports section.
  4. Optional. Select your desired merge options, such as Delete source branch, Squash commits, or Edit commit message.
  5. Select Merge when pipeline succeeds.

If a new comment is added to the merge request after you select Merge when pipeline succeeds, but before the pipeline completes, GitLab blocks the merge until you resolve all existing threads.

Cancel an auto-merge

If a merge request is set to MWPS, you can cancel it.

Prerequisites:

  • You must either be the author of the merge request, or a project member with at least the Developer role.
  • The merge request’s pipeline must still be in progress.

To do this:

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Merge requests.
  3. Scroll to the merge request reports section.
  4. Select Cancel auto-merge.

Status

Require a successful pipeline for merge

You can configure your project to require a complete and successful pipeline before merge. This configuration works for both:

As a result, disabling GitLab CI/CD pipelines does not disable this feature, but you can use pipelines from external CI providers with it.

Prerequisites:

  • Ensure CI/CD is configured to run a pipeline for every merge request.
  • You must have at least the Maintainer role in the project.

To enable this setting:

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Settings > Merge requests.
  3. Scroll to Merge checks, and select Pipelines must succeed. This setting also prevents merge requests from being merged if there is no pipeline, which can conflict with some rules.
  4. Select Save.

Allow merge after skipped pipelines

Introduced in GitLab 13.1.

When the Pipelines must succeed checkbox is checked, skipped pipelines prevent merge requests from being merged.

Prerequisite:

  • You must have at least the Maintainer role in the project.

To change this behavior:

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Settings > General.
  3. Expand Merge requests.
  4. Under Merge checks:
    • Select Pipelines must succeed.
    • Select Skipped pipelines are considered successful.
  5. Select Save.

Troubleshooting

Merge requests don’t merge when successful pipeline is required

If you require a successful pipeline for a merge, this setting can conflict with some use cases that do not generate pipelines, such as only/except or rules. Ensure your project runs a pipeline for every merge request, and that the pipeline is successful.

Ensure test parity between pipeline types

If a merge request triggers both a branch pipeline and a merge request pipeline, the success or failure of only the merge request pipeline is checked. If the merge request pipeline contains fewer jobs than the branch pipeline, it could allow code that fails tests to be merged, like in this example:

branch-pipeline-job:
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
  script:
    - echo "Testing happens here."

merge-request-pipeline-job:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - echo "No testing happens here. This pipeline always succeeds, and enables merge."
    - echo true

Instead, use branch (push) pipelines or merge request pipelines, when possible. For details on avoiding two pipelines for a single merge request, read the rules documentation.

Merged results pipeline allows merge, despite a failed branch pipeline

When the Pipelines must succeed setting is combined with the Merged results pipelines feature, failed branch pipeline may be ignored. Issue 385841 is open to track this.