🚂 Merge Trains GitLab : fusionner sans jamais casser main

📚 Introduction

Deux merge requests peuvent chacune passer leur pipeline avec un joli badge vert. Fusionnez-les l’une après l’autre et pourtant, main casse. Ce n’est pas un bug : chaque pipeline a testé sa branche isolément (ou combinée avec main au moment T), pas le résultat des deux changements réunis. Sur un projet avec plusieurs MR fusionnées par jour, ce scénario n’est pas une exception, c’est une statistique.

Les merge trains de GitLab répondent précisément à ce problème. L’idée : au lieu de fusionner chaque MR dès que son pipeline est vert, on les met en file d’attente, et on teste chacune contre le cumul de toutes celles qui la précèdent. Si ça passe, ça fusionne, dans l’ordre. Si ça casse, seule la MR fautive sort du train, sans bloquer les autres.

Cet article part du principe que vous connaissez déjà les fondamentaux de GitLab CI (stages, jobs, rules). On se concentre ici sur la mécanique des merge trains, leur activation, et comment adapter un .gitlab-ci.yml en conséquence — avec deux schémas pour visualiser le flux normal et la gestion d’un échec.

🔎 Qu’est-ce qu’un merge train, concrètement ?

Un merge train est une file d’attente ordonnée de merge requests en cours de fusion vers la même branche cible. Chaque MR qui y entre déclenche une pipeline testant non pas ses propres changements isolés, mais un commit spéculatif : la branche cible, plus les changements de toutes les MR placées avant elle dans le train, plus les siens. La documentation GitLab résume le problème que ça résout ainsi : deux merge requests peuvent chacune passer leur propre pipeline, mais leurs changements combinés peuvent tout de même entrer en conflit.

Ce mécanisme s’appuie sur les pipelines de résultats fusionnés (« merged results pipelines »), qui existent indépendamment des merge trains : elles testent déjà un commit temporaire combinant branche source et branche cible. Le merge train étend cette idée en chaînant plusieurs MR à la suite, chacune testée contre le cumul de celles qui la précèdent.

🧱 Le flux normal : validation cumulative

Prenons trois MR entrées dans le train dans cet ordre : !42, !45, !49. Voici ce qui se passe :

• !42 est testée sur main + !42. Pipeline verte → elle fusionne en premier.
• !45 est testée sur main + !42 + !45, même si !42 n’a pas encore fini de fusionner. GitLab lance les pipelines en parallèle pour ne pas ralentir le train.
• !49 est testée sur main + !42 + !45 + !49.

La règle de fusion est stricte : une MR ne fusionne réellement dans main que si son propre pipeline a réussi ET que toutes les MR placées avant elle ont déjà fusionné. Une pipeline verte ne suffit pas si le wagon précédent est encore en cours — GitLab attend son tour. C’est ce qui garantit un historique semi-linéaire : main avance toujours par ajouts validés dans l’ordre, jamais par un mélange non testé.

Par défaut, GitLab exécute jusqu’à 20 pipelines de merge train en parallèle sur un même projet ; cette limite est configurable par projet depuis GitLab 19.0.

🔍 Que se passe-t-il en cas d’échec ?

C’est là que le merge train montre son intérêt par rapport à une fusion manuelle séquentielle : un échec n’immobilise pas tout le monde.

Si la pipeline de !45 échoue :

1. GitLab retire !45 du train — elle repart en attente d’une correction, hors du flux.
2. GitLab relance immédiatement les pipelines de toutes les MR placées après elle dans le train, cette fois sans les changements de !45. !49 est donc retestée sur main + !42 + !49.
3. Les pipelines devenues redondantes (celles qui incluaient encore !45) sont annulées automatiquement.

Le train continue son chemin. !45 peut être corrigée et remise dans la file à son tour, sans avoir bloqué !49 une seule minute de plus que le temps de recalcul de sa pipeline.

🚀 Activer les merge trains sur son projet

Deux prérequis avant de commencer :

• Le projet doit être hébergé nativement sur GitLab (pas un miroir d’un dépôt externe comme GitHub ou Bitbucket).
• Vous devez être sur un plan Premium ou Ultimate — merge trains n’existe pas sur le plan Free.

L’activation se fait dans Settings > Merge requests > Merge options :

1. Cochez d’abord « Enable merged results pipelines » — c’est un prérequis technique, les merge trains s’appuient dessus.
2. Cochez ensuite « Enable merge trains ».
3. Enregistrez.

Une fois actif, un nouvel onglet « Merge trains » apparaît sous Code > Merge requests (disponible depuis GitLab 17.3), listant les MR actuellement en file et leur position.

🧰 Adapter son .gitlab-ci.yml

Contrairement à ce qu’on pourrait imaginer, activer les merge trains ne demande aucun mot-clé YAML particulier : GitLab orchestre le tout au niveau des paramètres du projet et du merge request. Le seul prérequis côté configuration est que le pipeline soit déjà taillé pour tourner en pipeline de merge request, avec un workflow ou des rules basés sur $CI_PIPELINE_SOURCE :

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Là où ça devient intéressant, c’est pour distinguer le contexte exact d’une pipeline de merge request. La variable prédéfinie $CI_MERGE_REQUEST_EVENT_TYPE prend l’une de ces trois valeurs :

• detached — pipeline classique de MR, teste uniquement la branche source.
• merged_result — teste le commit spéculatif branche source + branche cible.
• merge_train — teste le commit spéculatif cumulant en plus les MR précédentes dans le train.

C’est utile pour réserver les jobs les plus coûteux (suite e2e complète, tests de charge) au passage réel dans le train, plutôt que de les lancer à chaque pipeline de MR classique :

tests-e2e-completes:
  stage: test
  script:
    - ./scripts/run-e2e.sh
  rules:
    - if: $CI_MERGE_REQUEST_EVENT_TYPE == 'merge_train'

⚠️ Quelques précautions

• Conflit avec la cible = pas de pipeline. Une pipeline de résultats fusionnés (et donc de merge train) ne peut pas se lancer si la branche cible a divergé au point de créer un conflit textuel. Il faut d’abord rebaser ou merger main dans la MR.
• Le train consomme des ressources. Chaque MR en file déclenche une pipeline complète, potentiellement recalculée à chaque échec en amont. Sur un projet avec beaucoup de MR concurrentes et des pipelines longues, surveillez la charge sur vos runners.
• Ce n’est pas un raccourci pour des tests bâclés. Le merge train protège main des conflits sémantiques entre changements combinés ; il ne remplace pas une bonne couverture de tests dans chaque pipeline individuelle.
• 20 pipelines parallèles par défaut. Sur un train très actif, cette limite (configurable depuis GitLab 19.0, avec un mode d’application stricte depuis 19.3) peut mettre en pause l’ajout de nouvelles MR le temps que des places se libèrent.

🎉 Conclusion

Le merge train résout un problème que les pipelines de MR classiques, aussi bien conçues soient-elles, ne peuvent pas voir : la collision entre changements qui, pris séparément, sont chacun irréprochables. En mettant les fusions en file et en testant le cumul avant de merger dans l’ordre, GitLab garantit que main n’avance que par étapes déjà validées ensemble — et qu’un échec isolé ne bloque jamais tout le monde derrière.

Si votre projet fusionne plusieurs MR par jour sur une équipe de plus de deux ou trois développeurs, et que vous êtes sur un plan Premium ou Ultimate, c’est une des fonctionnalités GitLab CI/CD dont le rapport effort d’activation / valeur est le plus favorable : deux cases à cocher, zéro ligne de YAML obligatoire.

🔗 Liens utiles

• Merge trains — documentation officielle GitLab
• Merged results pipelines — documentation officielle
• Pipelines de merge request — documentation officielle
• Variables prédéfinies de GitLab CI/CD (CI_MERGE_REQUEST_EVENT_TYPE)
• Fondamentaux GitLab CI : comprendre le pipeline .gitlab-ci.yml