Keep Your Main Branch Green with GitLab Merge Trains

The problem: green pipelines, red main branch

It happens on busy teams: two feature branches both pass CI against main, but they touch the same file or configuration. When they merge within minutes of each other, the second change was never tested against the first. The result is a red main branch, an emergency revert, and a frustrated on-call engineer.

Reviewing every merge request in isolation does not guarantee that the combined state of the branch still builds and passes tests. Teams often respond by asking authors to rebase repeatedly, which slows down merges and does not fully eliminate integration risk.

What a merge train does

A merge train is a queue for merge requests targeting the same protected branch. Instead of merging each MR as soon as its pipeline passes, GitLab holds it behind earlier MRs in the train. Each MR is retested against the accumulated changes of the MRs ahead of it before it is allowed to merge.

Key terms:

• Merge request (MR): GitLab's term for a pull request.
• Protected branch: a branch where push and merge access are restricted, often main or master.
• Pipeline: the CI job sequence that builds and tests a change.

Worked example: enabling a merge train

This example assumes a self-managed or SaaS GitLab instance with a protected target branch. UI paths and permission names vary by GitLab version, so confirm the exact menu labels in your instance before changing settings.

1. Go to your project, then Settings → Repository → Merge Trains. Enable Merge trains for the target branch, such as main.
2. Confirm your role. You generally need the Maintainer role or a custom role with merge-train permissions to configure the setting. Developers can usually create MRs that join the train.
3. Create two MRs targeting main from active feature branches.
4. Watch the merge train widget on each MR. The first MR to be merged typically shows a normal pipeline. The second MR should show a Merge train status and wait until the first MR's pipeline succeeds and it merges.
5. If the first MR's pipeline fails, GitLab removes it from the train and evaluates the next MR against the branch as it currently stands.

Where to run: GitLab project UI, not a local terminal.

Permissions: Maintainer or Owner to enable the setting; any user with merge access can create MRs that participate.

Expected check: After enabling, open an MR targeting the protected branch. The merge widget should display a merge train section when another MR is ahead of it in the queue.

Risk: A large train can delay urgent fixes because every MR waits for the ones ahead. Do not enable merge trains on a branch that receives frequent emergency hotfixes without a separate fast path.

To disable: Return to Settings → Repository → Merge Trains and clear the merge train option for that branch.

Trade-offs and limitations

Merge trains reduce integration failures, but they trade throughput for safety. Each additional MR in the queue adds CI time. If your team opens twenty MRs a day against main, the last MR may wait through many pipelines before it can merge.

The feature also does not replace small, reviewable changes. A large MR still takes longer to validate and blocks more of the train while it runs.

Finally, merge trains require the target branch to be protected. If your team uses unprotected feature branches as integration targets, this feature will not apply.

How to verify it is working

1. Open two MRs against the same protected branch.
2. Merge the first MR.
3. Confirm the second MR's pipeline runs against a branch state that includes the first MR's changes.
4. Check the project's Merge Trains settings page for timeout, pause, and stop controls if you need to interrupt a stalled queue.

Closing recommendation

Start with one protected branch and a small team. Monitor how long MRs spend in the train and whether critical fixes are delayed. If queue times become painful, consider splitting the branch strategy or adding a separate fast-track path for urgent patches.

Verification note: This draft describes established GitLab behavior based on public documentation summaries, but it has not been tested against a live instance. Confirm menu paths, permission names, and pipeline behavior in your GitLab version before adopting this workflow.