doc/user/project/merge_requests/auto_merge.md
{{< details >}}
{{< /details >}}
{{< history >}}
auto_merge_labels_mr_widget. Enabled by default.auto_merge_labels_mr_widget removed.merge_when_checks_pass and additional_merge_when_checks_ready. Disabled by default.additional_merge_when_checks_ready with the flag merge_when_checks_pass in GitLab 17.1.merge_when_checks_pass removed.merge_when_checks_pass_merge_train. Disabled by default.merge_when_checks_pass_merge_train removed.{{< /history >}}
If the content of a merge request is ready to merge, you can select Set to auto-merge. The merge request auto-merges when all required checks complete successfully, and you don't need to remember to manually merge the merge request.
Merge checks enable you to focus on reviewing a merge request's contents, and use project settings to determine their mergeability. When you review a merge request, if you approve of the merge request's changes, set it to auto-merge. GitLab enforces your project settings, and until the merge request satisfies all merge checks (like required Code Owner and approval rules), it cannot merge. After satisfying all required merge checks, the merge request merges, with no action required from you.
Merge checks include a passing CI/CD pipeline, and much more:
For a full list of checks and their API equivalents, see merge status.
After you set auto-merge, you can't change which issues auto-close when the merge request merges.
Prerequisites:
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:
In the top bar, select Search or go to and find your project.
In the left sidebar, select Code > Merge requests.
Select the merge request to edit.
Scroll to the merge request reports section.
Optional. Select your desired merge options, such as Delete source branch, Squash commits, or Edit commit message.
Review the contents of the merge request reports section. If it contains an issue closing pattern, confirm that the issue should close when the merge request merges:
Select Set to auto-merge.
If you comment on the merge request after setting it to auto-merge, but before the pipeline completes, the merge is blocked until you resolve all existing threads.
You can cancel auto-merge on a merge request.
Prerequisites:
To do this:
If the pipeline succeeds, the merge request merges. If the pipeline fails, the author can either retry any failed jobs, or push new commits to fix the failure:
For stricter control on pipeline status, you can also require a successful pipeline before 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:
To enable this setting:
If multiple pipeline types run for the same merge request, merge request pipelines take precedence over other pipeline types. For example, an older but successful merge request pipeline allows a merge request to merge, despite a newer but failed branch pipeline.
When you set Pipelines must succeed for a project, skipped pipelines prevent merge requests from merging.
Prerequisites:
To change this behavior:
{{< history >}}
{{< /history >}}
If your merge request should not merge before a specific date and time, set a Merge can start date. This value sets when the merge (or merge train) can start. The exact time of merge can vary, however, depending on the satisfaction of other merge checks or the length of your merge train.
Prerequisites:
To do this:
After scheduled date, then select a date and time.In some cases, you can require a successful pipeline for merge, but be unable to merge a merge request with no failed pipelines. The setting requires the existence of a successful pipeline, not the absence of failed pipelines. A merge request with no pipelines at all is not considered to have a successful pipeline, and cannot merge.
When you enable this setting, use rules
or workflow:rules to ensure pipelines
run for every merge request.
In some cases, you can require a successful pipeline for merge, but still merge a merge request with a failed pipeline.
Merge request pipelines have the highest priority for the Pipelines must succeed setting. If multiple pipeline types run for the same merge request, GitLab checks only the merge request pipelines for success.
Merge requests can have multiple pipelines if:
rules configuration that causes duplicate pipelines:
one merge request pipeline and one branch pipeline. In this case, the status of the
latest merge request pipeline determines if a merge request can merge, not the branch pipeline.In all cases, update your CI/CD configuration to prevent multiple pipeline types for the same merge request.