Skip to content

Merge Trains

Available only in the Enterprise version

How It Works

The merge trains feature is a logical extension of the Merge Result Pipeline (MRP) functionality.

MRP provides a snapshot of the project's state and gives users insight into your project's status at a specific point in time before merging. For example, you create a merge request (MR) into the main branch and run MRP for your branch. However, at that moment, your colleague might have already merged their branch into the project's main branch, forcing you to rerun MRP to perform all necessary tests.

Merge trains help avoid such races to verify the project's current state before merging a branch. They operate on the following principle:

  • When merging a branch from an MR into the main branch, it is placed in a separate queue where each merge request is verified by the merge result pipeline after merging with the previous one in the queue.

  • Until the MRP completes with one of the statuses (Success or Error), the MR will display the status "Added to the merge train." If the MRP completes successfully, the MR will be merged as usual, following the configured merge rules.

  • If one of the MRPs fails, it is removed from the queue, and the next MRP is compared with the last successful one. The merge request whose MRP failed is reopened with the status "Conflict during merge train."

This feature is particularly useful in large teams where many developers work on the same project.

Example

Consider an example with four merge requests (A, B, C, D) queued for the merge train with the master branch. Before merging, each branch had to pass MRP with the master branch as part of its MR.

If the merge train for A and master succeeds, merge request B will run MRP with the commit after merging A and master. If the MRP fails, the merge request is reopened to resolve the issues, and the queue (C, D) is redefined. The next MRP (C) will run with the commit after merging A and master, following the same principle.

Upon successful merging, the associated merge requests receive the "Merged" status, as if they were merged manually.

Configuring Merge Trains

The merge trains feature can be enabled in the project settings under CI/CD Settings. To activate it, the Merge Result Pipeline feature must be used.

Activation in settings

When merging a branch, an additional hint will appear, indicating that the branch will be added to the merge train queue before merging.

Display on the MR page

The current pipeline queue is displayed on the CI/CD page. If one of the pipelines fails, the queue is redefined without including it.

Display on the CI/CD page

Each associated merge request will have a special status. All merge requests can be filtered by this status.

Display on the MR list page

Merge train statuses on the MR list page

Automatic translation!

This page has been automatically translated. The text may contain inaccuracies