Merge when pipeline succeeds

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 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.

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 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 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.

By default, all threads must be resolved before you see the Merge when pipeline succeeds button. If someone adds a new comment after the button is selected, but before the jobs in the CI pipeline are complete, the merge is blocked until you resolve all existing threads.

Only allow merge requests to be merged if the pipeline succeeds

You can prevent merge requests from being merged if their pipeline did not succeed or if there are threads to be resolved. This works for both:

• GitLab CI/CD pipelines
• Pipelines run from an external CI integration

As a result, disabling GitLab CI/CD pipelines 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.
2. Expand the Merge requests section.
3. In the Merge checks subsection, select the Pipelines must succeed checkbox.
4. Press Save for the changes to take effect.

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 or rules are used and they don't generate any pipelines.

You should ensure that there is always a pipeline 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:

branch-pipeline-job:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push"'
  script:
    - echo "Code testing scripts here, for example."

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 for details on avoiding two pipelines for a single merge request.

Skipped pipelines

Introduced in GitLab 13.1.

When the Pipelines must succeed checkbox is checked, skipped pipelines prevent merge requests from being merged. To change this behavior:

1. Navigate to your project's Settings > General page.
2. Expand the Merge requests section.
3. In the Merge checks subsection, ensure Pipelines must succeed is checked.
4. In the Merge checks subsection, select the Skipped pipelines are considered successful checkbox.
5. Press Save for the changes to take effect.

From the command line

You can use Push Options to enable merge when pipeline succeeds for a merge request when pushing from the command line.