1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
---
stage: Verify
group: Pipeline Execution
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/#assignments
type: reference
last_update: 2019-07-03
---
# Merge trains **(PREMIUM)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9186) in GitLab 12.0.
> - [Squash and merge](../../user/project/merge_requests/squash_and_merge.md) support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13001) in GitLab 12.6.
INFO:
Get merge trains and more in GitLab Ultimate.
[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-ci-cd-external-docs).
For more information about why you might want to use merge trains, read [How merge trains keep your master green](https://about.gitlab.com/blog/2020/01/30/all-aboard-merge-trains/).
When [pipelines for merged results](pipelines_for_merged_results.md) are
enabled, the pipeline jobs run as if the changes from your source branch have already
been merged into the target branch.
However, the target branch may be changing rapidly. When you're ready to merge,
if you haven't run the pipeline in a while, the target branch may have already changed.
Merging now could introduce breaking changes.
*Merge trains* can prevent this from happening. A merge train is a queued list of merge
requests, each waiting to be merged into the target branch.
Many merge requests can be added to the train. Each merge request runs its own merged results pipeline,
which includes the changes from all of the other merge requests in *front* of it on the train.
All the pipelines run in parallel, to save time.
If the pipeline for a merge request fails, the breaking changes are not merged, and the target
branch is unaffected. The merge request is removed from the train, and all pipelines behind it restart.
If the pipeline for the merge request at the front of the train completes successfully,
the changes are merged into the target branch, and the other pipelines continue to
run.
To add a merge request to a merge train, you need [permissions](../../user/permissions.md) to merge or push to the
target branch.
Each merge train can run a maximum of **twenty** pipelines in parallel.
If more than twenty merge requests are added to the merge train, the merge requests
are queued until a slot in the merge train is free. There is no limit to the
number of merge requests that can be queued.
## Merge train example
Three merge requests (`A`, `B` and `C`) are added to a merge train in order, which
creates three merged results pipelines that run in parallel:
1. The first pipeline runs on the changes from `A` combined with the target branch.
1. The second pipeline runs on the changes from `A` and `B` combined with the target branch.
1. The third pipeline runs on the changes from `A`, `B`, and `C` combined with the target branch.
If the pipeline for `B` fails, it is removed from the train. The pipeline for
`C` restarts with the `A` and `C` changes, but without the `B` changes.
If `A` then completes successfully, it merges into the target branch, and `C` continues
to run. If more merge requests are added to the train, they now include the `A`
changes that are included in the target branch, and the `C` changes that are from
the merge request already in the train.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
Watch this video for a demonstration on [how parallel execution
of merge trains can prevent commits from breaking the default
branch](https://www.youtube.com/watch?v=D4qCqXgZkHQ).
## Prerequisites
To enable merge trains:
- You must have the [Maintainer role](../../user/permissions.md).
- You must be using [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or later.
- In GitLab 13.0 and later, you need [Redis](https://redis.io/) 5.0 or later.
- Your repository must be a GitLab repository, not an
[external repository](../ci_cd_for_external_repos/index.md).
## Enable merge trains
To enable merge trains for your project:
1. If you are on a self-managed GitLab instance, ensure the [feature flag](#merge-trains-feature-flag) is set correctly.
1. [Configure your CI/CD configuration file](merge_request_pipelines.md#configure-pipelines-for-merge-requests)
so that the pipeline or individual jobs run for merge requests.
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Settings > General**.
1. Expand **Merge requests**.
1. In the **Merge method** section, verify that **Merge commit** is selected.
You cannot use **Merge commit with semi-linear history** or **Fast-forward merge** with merge trains.
1. In the **Merge options** section, select **Enable merged results pipelines** (if not already selected) and **Enable merge trains**.
1. Select **Save changes**.
In GitLab 13.5 and earlier, there is only one checkbox, named
**Enable merge trains and pipelines for merged results**.
WARNING:
If you select the check box but don't configure your CI/CD to use
pipelines for merge requests, your merge requests may become stuck in an
unresolved state or your pipelines may be dropped.
## Start a merge train
To start a merge train:
1. Visit a merge request.
1. Select **Start merge train**.
Other merge requests can now be added to the train.
## Add a merge request to a merge train
To add a merge request to a merge train:
1. Visit a merge request.
1. Select **Add to merge train**.
If pipelines are already running for the merge request, you cannot add the merge request
to the train. Instead, you can schedule to add the merge request to a merge train **when the latest
pipeline succeeds**.
## Remove a merge request from a merge train
1. Visit a merge request.
1. Select **Remove from merge train**.
If you want to add the merge request to a merge train again later, you can.
## View a merge request's current position on the merge train
After a merge request has been added to the merge train, the merge request's
current position is displayed under the pipeline widget:
## Immediately merge a merge request with a merge train
If you have a high-priority merge request (for example, a critical patch) that must
be merged urgently, you can bypass the merge train by using the **Merge Immediately** option.
This is the fastest option to get the change merged into the target branch.
WARNING:
Each time you merge a merge request immediately, the current merge train
is recreated and all pipelines restart.
## Troubleshooting
### Merge request dropped from the merge train immediately
If a merge request is not mergeable (for example, it's a draft merge request or it has a merge
conflict), the merge train drops your merge request automatically.
In these cases, the reason for dropping the merge request is in the **system notes**.
To check the reason:
1. Open the merge request that was dropped from the merge train.
1. Select the **Discussion** tab.
1. Find a system note that includes either:
- **... removed this merge request from the merge train because ...**
- **... aborted this merge request from the merge train because ...**
The reason is given in the text after the **because ...** phrase.
### Merge When Pipeline Succeeds cannot be chosen
[Merge When Pipeline Succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md)
is currently unavailable when merge trains are enabled.
See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/12267)
for more information.
### Merge train pipeline cannot be retried
When a pipeline for merge trains fails the merge request is dropped from the train and the pipeline can't be retried.
Pipelines for merge trains run on the merged result of the changes in the merge request and
the changes from other merge requests already on the train. If the merge request is dropped from the train,
the merged result is out of date and the pipeline can't be retried.
Instead, you should [add the merge request to the train](#add-a-merge-request-to-a-merge-train)
again, which triggers a new pipeline.
### Unable to add to merge train with message "The pipeline for this merge request failed."
Sometimes the **Start/Add to merge train** button is not available and the merge request says,
"The pipeline for this merge request failed. Please retry the job or push a new commit to fix the failure."
This issue occurs when [**Pipelines must succeed**](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds)
is enabled in **Settings > General > Merge requests**. This option requires that you
run a new successful pipeline before you can re-add a merge request to a merge train.
Merge trains ensure that each pipeline has succeeded before a merge happens, so
you can clear the **Pipelines must succeed** checkbox and keep
**Enable merge trains and pipelines for merged results** (merge trains) selected.
If you want to keep the **Pipelines must succeed** option selected along with merge
trains, create a new pipeline for merged results when this error occurs:
1. On the **Pipelines** tab, select **Run pipeline**.
1. Select **Start/Add to merge train when pipeline succeeds**.
See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/35135)
for more information.
### Merge trains feature flag **(PREMIUM SELF)**
In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/244831),
you can [enable or disable merge trains in the project settings](#enable-merge-trains).
In GitLab 13.5 and earlier, merge trains are automatically enabled when
[pipelines for merged results](pipelines_for_merged_results.md) are enabled.
To use pipelines for merged results without using merge trains, you can enable a
[feature flag](../../user/feature_flags.md) that blocks the merge trains feature.
[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
can enable the feature flag to disable merge trains:
```ruby
Feature.enable(:disable_merge_trains)
```
After you enable this feature flag, all existing merge trains are cancelled and
the **Start/Add to merge train** button no longer appears in merge requests.
To disable the feature flag, and enable merge trains again:
```ruby
Feature.disable(:disable_merge_trains)
```
|
