Commit d401ae5b authored by Marcel Amirault's avatar Marcel Amirault Committed by Suzanne Selhorn

Update docs for mwps

parent 6d445705
--- ---
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 type: reference, concepts
--- ---
# Merge when pipeline succeeds # Merge when pipeline succeeds
When reviewing a merge request that looks ready to merge but still has one or When reviewing a merge request that looks ready to merge but still has a
more CI jobs running, you can set it to be merged automatically when the pipeline running, you can set it to merge automatically when the
jobs pipeline succeeds. This way, you don't have to wait for the jobs to pipeline succeeds. This way, you don't have to wait for the pipeline to
finish and remember to merge the request manually. finish and remember to merge the request manually.
![Enable](img/merge_when_pipeline_succeeds_enable.png) ![Enable](img/merge_when_pipeline_succeeds_enable.png)
## How it works ## How it works
When you hit the "Merge When Pipeline Succeeds" button, the status of the merge When you click "Merge When Pipeline Succeeds", the status of the merge
request will be updated to represent the impending merge. If you cannot wait request is updated to show the impending merge. If you can't wait
for the pipeline to succeed and want to merge immediately, this option is for the pipeline to succeed, you can choose **Merge immediately**
available in the dropdown menu on the right of the main button. 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 The author of the merge request and project members with developer permissions can
cancel the automatic merge if they find a reason why it shouldn't be merged cancel the automatic merge at any time before the pipeline finishes.
after all.
![Status](img/merge_when_pipeline_succeeds_status.png) ![Status](img/merge_when_pipeline_succeeds_status.png)
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, When the pipeline fails, the author gets a chance to retry any failed jobs,
or to push new commits to fix the failure. or to push new commits to fix the failure.
When the jobs are retried and succeed on the second try, the merge request 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 is automatically merged. When the merge request is updated with
new commits, the automatic merge is automatically canceled to allow the new new commits, the automatic merge is canceled to allow the new
changes to be reviewed. changes to be reviewed.
## Only allow merge requests to be merged if the pipeline succeeds ## 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: ...@@ -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) - 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) 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: CI providers with this feature. To enable it, you must:
1. Navigate to your project's **Settings > General** page. 1. Navigate to your project's **Settings > General** page.
...@@ -50,14 +52,40 @@ CI providers with this feature. To enable it, you must: ...@@ -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. In the **Merge checks** subsection, select the **Pipelines must succeed** checkbox.
1. Press **Save** for the changes to take effect. 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.
![Pipelines must succeed settings](img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png) ### 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-pipeline-job:
merge request from the UI, until you make all relevant jobs pass. rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
script:
- echo "No tests run, but this pipeline always succeeds and enables merge."
- echo true
```
![Only allow merge if pipeline succeeds message](img/merge_when_pipeline_succeeds_only_if_succeeds_msg.png) 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 ### Skipped pipelines
...@@ -72,20 +100,10 @@ merge requests from being merged. To change this behavior: ...@@ -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. In the **Merge checks** subsection, select the **Skipped pipelines are considered successful** checkbox.
1. Press **Save** for the changes to take effect. 1. Press **Save** for the changes to take effect.
### Limitations ## From the command line
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.
For example, to that on merge requests there is always a passing job even though `only/except` rules may not generate any other jobs: You can use [Push Options](../push_options.md) to enable merge when pipeline succeeds
for a merge request when pushing from the command line.
```yaml
enable_merge:
only: [merge_requests]
script:
- echo true
```
<!-- ## Troubleshooting <!-- ## Troubleshooting
...@@ -98,8 +116,3 @@ questions that you know someone might ask. ...@@ -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`. 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 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. --> 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.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment