skip to content

In GitLab, why can two merge requests that each passed a merged results pipeline still break main, and how does a merge train prevent that?

level: seniorimportance: should knowfreq 15%

answer

  1. each tested against main alone
  2. a temporary merged commit
  3. queue: A, then A+B, then A+B+C
  4. a failure drops one, restarts the rest
  5. parallel limit and enforcement levels

basics

~20 s

A merged results pipeline tests one merge request combined with the current target branch, not with others merging at the same time. A merge train queues merge requests and tests each against the target plus every request ahead, merging in order.

solid answer

~50 s

A **merged results pipeline** runs on a temporary commit that merges the source branch into the *current* target branch, so it catches conflicts with what is already on main — but two merge requests tested that way never see each other, and both can merge green and break main together. A **merge train** (Premium and Ultimate) queues them: the first runs on A plus main, the second on A+B plus main, the third on A+B+C, all in parallel, and each merges only after its pipeline passes and everything ahead of it has merged. If B fails, B is dropped, A carries on, and C restarts on A+C. It needs merge request pipelines in the configuration plus **Enable merged results pipelines** and **Enable merge trains**. Since 19.0 a project can set **Maximum parallel pipelines per merge train** (default 20), and since 19.3 **Merge train enforcement** can stop people bypassing the train.

go deeper

for a junior

Know that a merge train is a GitLab queue of merge requests that are tested together before each one merges into the target branch.

for a middle

Explain how a merged results pipeline differs from a plain branch pipeline, and why it still misses conflicts between merge requests merging at the same time.

for a senior

Show how a train behaves when an entry fails or someone merges immediately, and how the parallel limit and enforcement levels shape cost and safety.

for a principal

Judge when a merge train is worth its extra CI load and queueing for a team, and whether to enforce it or allow bypass for urgent fixes.

## The gap a merged results pipeline leaves A plain branch pipeline tests the source branch as it is. A **merged results pipeline** (Premium and Ultimate, switched on with **Enable merged results pipelines**) goes further: it tests a **temporary merged commit** that combines the source branch with the latest target branch. That commit exists in neither branch, but it shows whether the change still works with what has already landed. If the two conflict, GitLab runs an ordinary merge request pipeline instead. What it cannot see is **other merge requests that are about to merge**. Two requests, A and B, can each pass a pipeline against today's main; if A renames a function that B starts calling, both merge green and main breaks, even though every pipeline succeeded. ## How a merge train closes it A **merge train** turns merging into a queue in which each entry is tested against everything ahead of it: 1. The first request to join, A, gets a pipeline on **A + target branch** — the same thing a merged results pipeline tests. 2. B joins behind it and gets a pipeline on **A + B + target**. 3. C joins and gets **A + B + C + target**. 4. The pipelines run **in parallel**, and each request merges only when its own pipeline has passed and every request ahead of it has merged. People join a train with **Merge** when no pipeline is running, or **Set to auto-merge** when one is. The merge train details page shows the queue for each target branch. ## When something goes wrong - **A pipeline fails.** That request is removed and not merged. Requests ahead carry on; pipelines for requests behind it are **cancelled and restarted** without its changes. If B fails, C restarts on A + C. - **A failed train pipeline cannot be retried**, because the combination it tested is gone; the request has to rejoin. - **Requests are also dropped** when marked as draft, closed, when their source branch is updated, when a merge check fails or a conflict appears with earlier entries; the reason appears in the request's activity as a system note. - **Merge immediately** merges past the train, cancels every train pipeline and restarts the whole train with new pipelines — useful for a critical fix, expensive otherwise. - New discussion threads do **not** remove a request that is already on the train, even where all threads must be resolved. ## Turning it on and keeping it honest Prerequisites: the CI configuration must create **merge request pipelines** (a configuration subject of its own), the repository must be a GitLab repository rather than an external one connected for CI/CD, and a Maintainer enables both settings in the merge request options. | Setting | Since | What it does | |---|---|---| | **Enable merged results pipelines** | earlier releases | test the merged result; required first | | **Enable merge trains** | earlier releases | queue merges as a train | | **Maximum parallel pipelines per merge train** | 19.0 | default 20; extra requests wait for a slot, `1` means strictly sequential; capped by the instance limit | | **Merge train enforcement** | 19.3 (19.2 behind a flag) | **Allow bypass** (default), **Enforce for all users**, **Enforce with Owner override** | When enforcement is on, GitLab hides the **Merge immediately** options, the REST and GraphQL APIs reject direct merges, and auto-merge routes every merge to the train; under **Enforce with Owner override**, Owners and administrators can still bypass it for individual merge requests. ## Costs and trade-offs - **CI load grows with queue depth and failures.** Every failure restarts the pipelines behind it, so a flaky test suite turns a train into a stream of reruns. Stabilise tests before you rely on a train. - **The parallel limit trades throughput for cost.** A low limit saves runners but makes the queue wait; the default of 20 assumes spare runner capacity. - **Bypass is a policy decision.** **Allow bypass** keeps urgent fixes fast but lets anyone with merge permission skip the guarantee; enforcement removes that, with **Enforce with Owner override** as the middle ground. - **It guarantees the target branch, not speed.** For projects where merges are rare, merged results pipelines alone already catch most integration problems.

  • In a GitLab merge train holding A, B and C, what happens when B's pipeline fails?
    B is removed from the train and not merged. A's pipeline keeps running. C's pipeline, which tested A+B+C, is cancelled and a new one starts on A+C with the target branch. If A then passes it merges, and C continues. B's failed train pipeline cannot be retried; B has to rejoin the train.
  • Why is Merge immediately expensive on a GitLab merge train?
    It merges the request regardless of the train, which invalidates every combination the train was testing. GitLab cancels all the other train pipelines, starts a new train with the same merge requests, and runs a fresh pipeline for each one that now includes the merged commits. On a long train that is a full rerun.
  • In GitLab 19.4, how do you stop maintainers from bypassing a merge train?
    Set **Merge train enforcement** in the merge request settings, generally available since 19.3. **Enforce for all users** makes every merge go through the train with no exceptions; **Enforce with Owner override** lets Owners and administrators bypass it for individual merge requests. With enforcement on, GitLab hides the **Merge immediately** options, the APIs reject direct merges and auto-merge routes to the train.

  • A merged results pipeline already tests a merge request against all other queued ones.
  • Merge train pipelines always run one at a time, so a train never tests in parallel.
  • When one merge request fails, the whole train is cancelled and nothing merges.
  • A failed merge train pipeline can simply be retried to keep its place.
  • Merge trains work on GitLab Free once merge request pipelines are configured.

Assumes GitLab 19.4: the per-project Maximum parallel pipelines per merge train setting (default 20) arrived in 19.0, and Merge train enforcement levels, introduced behind a flag in 19.2, became generally available in 19.3; under the default Allow bypass anyone with merge permission can still skip the train.