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