Une merge queue pour agents IA est le moyen le plus fiable de garder main au vert dès que vous faites tourner plus d’un agent à la fois. Avec un seul agent, pas de drame : il travaille sur une branche, vous la regardez, vous fusionnez. Mais quand trois ou quatre agents se mettent à terminer leur travail sur leurs propres branches, tout change. Chaque branche passe seule, vous les fusionnez l’une après l’autre, et main est rouge.
Cet article explique pourquoi les branches d’agents parallèles cassent main, comment une merge queue y remédie, et comment la merge queue d’AgentVera fonctionne, étape par étape.
Vert seul, rouge ensemble
Partons d’un exemple. Main contient une fonction formatPrice(amount). Vous lancez deux agents en même temps :
- L’agent A ajoute un paramètre de devise :
formatPrice(amount, currency), et met à jour chaque appel. - L’agent B construit un nouvel écran de facture qui appelle
formatPrice(amount).
Les deux branches partent du même main. Les tests de A passent, car dans le monde de A l’écran de facture n’existe pas. Les tests de B passent, car dans le monde de B la fonction prend encore un argument. Git ne voit pas non plus de conflit : les deux branches ont touché des fichiers différents.
Vous fusionnez A, puis B. Git ne dit rien. Mais main appelle maintenant une fonction à deux paramètres avec un seul argument, et la vérification des types échoue.
C’est un conflit sémantique : pas de conflit textuel, et pourtant les changements se cassent mutuellement. Les agents parallèles le rendent plus fréquent parce que :
- Les agents ne se voient pas. Chacun travaille dans son propre worktree et ignore ce que font les autres.
- Les branches s’accumulent vite. En milieu d’après-midi, cinq ou six branches peuvent attendre.
- Chaque branche a été testée sur une vieille base. Plus une branche attend, plus sa base est périmée.
- Fusionner dans l’ordre à la main est fastidieux. Après chaque fusion, vous mettez à jour la branche suivante, relancez les tests et réglez les conflits. On finit par sauter cette étape.
Qu’est-ce qu’une merge queue ?
Une merge queue met en file les branches qui attendent d’être intégrées et fusionne chacune sur la pointe actuelle de la branche cible, puis teste ce résultat. L’idée est simple : avant qu’une branche soit intégrée, testez à quoi ressemblera réellement main après son intégration.
Comparaison avec la fusion à la main :
| Fusion à la main | Merge queue | |
|---|---|---|
| Sur quoi tournent les tests | La base propre de la branche | Pointe actuelle de main + la branche |
| Conflits sémantiques | Découverts après avoir touché main | Détectés avant l’intégration |
| Ordre | Le premier qui clique | Ordre de la file |
| Une branche cassée | Casse main | Est rejetée, main reste propre |
GitHub propose aussi une merge queue au niveau du dépôt, qui met en file les pull requests et les teste ensemble avec la dernière version de la branche cible. La file d’AgentVera applique la même idée sur votre poste, pour les branches de vos agents, et ajoute en chemin des agents qui résolvent les conflits de fusion et corrigent les vérifications en échec.
Comment fonctionne la merge queue d’AgentVera
La file vit dans l’application de bureau sous Details → Automation → Merge queue. Chaque projet a une file ; dans un projet multi-dépôts, chaque dépôt a sa propre file et ses propres réglages. Les branches sont intégrées une par une.
1. Une branche entre dans la file
Il y a trois façons d’y entrer :
- À la main : saisissez le nom de la branche dans le champ Branch, donnez-lui éventuellement un Title, et appuyez sur Add to queue.
- Depuis une équipe parallèle : quand une équipe parallèle termine, appuyez sur Queue pour envoyer sa branche d’intégration.
- Depuis une automatisation : choisissez Add to the merge queue comme livraison d’une règle d’automatisation, et la branche de l’agent terminé entre directement dans la file.
Les cartes de la boîte de revue proposent aussi Send to the merge queue. Chaque élément indique son origine : manuelle, équipe parallèle ou automatisation.
2. Elle est fusionnée sur la pointe actuelle de la cible
Quand son tour vient, la branche est fusionnée sur la pointe actuelle de la cible dans le worktree séparé propre à la file. Votre dossier de travail et ceux de vos agents ne sont pas touchés. Si le dépôt a un remote, la cible est d’abord récupérée (fetch) et la fusion se fait par-dessus la dernière version d’origin.
Vous choisissez la stratégie dans les réglages : Merge commit ou Squash. Si la branche est déjà contenue dans la cible, l’élément est marqué comme intégré.
3. Un conflit fait appel à un agent
Si la fusion entre en conflit, la file ne s’arrête pas. Elle ouvre un agent de résolution et l’élément passe en « resolving conflicts ». L’agent reçoit pour consigne de conserver l’intention des deux côtés, de ne laisser aucun marqueur de conflit et de commiter le résultat.
Quand l’agent rend la main, AgentVera ne le croit pas sur parole. Elle cherche des fichiers non fusionnés, recherche les marqueurs <<<<<<< et >>>>>>> et confirme que la branche est réellement fusionnée. Si l’un de ces points échoue, l’élément échoue et n’est pas intégré.
Avec le modèle automatique activé, le modèle du résolveur est choisi selon la difficulté du travail.
4. La vérification tourne sur le résultat fusionné
Une fois le résultat fusionné prêt, la file lance une commande de vérification. Laissez Check vide et elle utilise la commande de test du projet, ou écrivez la vôtre, comme pnpm typecheck && pnpm test.
Si la vérification échoue, l’agent de résolution reçoit la fin de la sortie et tente de corriger. Il y a au plus deux tours de correction. Si la vérification est toujours rouge, l’élément est rejeté et la file passe au suivant. La branche cassée n’atteint jamais main.
C’est exactement ce qui se passe dans l’exemple formatPrice : la branche de B est fusionnée sur un main qui contient déjà A, la vérification des types échoue, le résolveur met à jour l’appel de l’écran de facture avec la nouvelle signature, et la vérification passe au vert.
5. Approbation et intégration
Une branche qui passe est prête. Par défaut, Land passing branches automatically est désactivé : l’élément attend donc en « ready, awaiting approval » et vous recevez une notification. Jetez un œil et appuyez sur Land quand vous êtes satisfait.
L’intégration se déroule ainsi :
- Avec un remote, le résultat fusionné est poussé sur la branche cible. Les dépôts GitHub utilisent la connexion GitHub de votre ordinateur.
- Sans remote, la branche cible locale est avancée en fast-forward. Elle n’est jamais déplacée sous un travail non commité.
- Si la cible a bougé entre-temps, l’élément est reconstruit sur la nouvelle pointe et revérifié. Cela arrive au plus trois fois ; si la cible continue de bouger, l’élément échoue.
Fermez et rouvrez l’application : le travail interrompu n’est pas perdu, il retourne dans la file.
Réglages
Il y en a peu, et ils sont tous dans le même onglet :
| Réglage | Ce qu’il fait | Par défaut |
|---|---|---|
| Target branch | La branche sur laquelle le travail est intégré | Vide : branche par défaut |
| Merge | Merge commit ou Squash | Merge commit |
| Check | Commande lancée sur le résultat fusionné | Vide : la commande de test du projet |
| Land passing branches automatically | Intègre les branches qui passent sans approbation | Désactivé |
Pour les éléments en file, vous pouvez réordonner avec Up et Down, en arrêter un avec Cancel, et relancer un élément échoué ou annulé avec Retry. Chaque élément a son propre journal et son historique, et ceux qui ont une pull request disposent d’un bouton pour l’ouvrir sur GitHub.
La file partage les ressources avec les autres tâches de fond et passe en premier : les fusions passent avant les automatisations et les équipes parallèles. Les agents que vous lancez vous-même ne sont jamais mis en file.
Équipes parallèles et file ensemble
La merge queue rapporte le plus avec une équipe parallèle. Une équipe parallèle découpe un gros travail en huit parties au plus ; par défaut trois agents tournent en même temps, chacun dans son propre worktree. Les parties sont fusionnées dans une branche d’intégration, et un agent d’intégration gère les conflits et la vérification.
Quand l’équipe termine, vous avez une branche d’intégration. Appuyez sur Queue pour l’envoyer. Une autre équipe ou une automatisation a peut-être envoyé quelque chose vers main entre-temps ; la file les prend tous dans l’ordre, en testant chacun sur le dernier main.
Pour la vue d’ensemble du travail avec plusieurs agents, voir les agents de code en parallèle.
Erreurs fréquentes
- Une vérification vide et aucune commande de test. La file fusionne quand même, mais sans rien à vérifier elle ne peut pas détecter les conflits sémantiques. Définissez la commande de test du projet ou mettez une commande dans Check.
- Uniquement des tests unitaires. Beaucoup de casses comme celle ci-dessus apparaissent dans la vérification des types ou le build. Ajoutez-les à la vérification.
- Activer l’intégration automatique dès le premier jour. N’activez pas Land passing branches automatically avant d’avoir observé la file un moment. Approuvez à la main pendant quelques semaines d’abord.
- Des branches énormes. La file les accepte, mais les risques de conflits et d’échecs grandissent avec la taille. Donnez aux agents des tâches petites et ciblées.
- Ignorer les éléments rejetés. Un rejet signale généralement un vrai conflit de conception. Lisez son journal, et renvoyez le travail à l’agent avec une note si besoin.
Une journée type
Le matin
Vous lancez trois agents sur trois tâches : la page de paiement, l’API de reporting et une mise à jour de dépendance. Chacun travaille dans son propre worktree. Il y a aussi un échec de CI de la nuit dernière ; une règle d’automatisation l’a déjà détecté et a envoyé le correctif dans la file.
Fin de matinée
Quand les agents terminent, vous ouvrez leurs cartes dans la boîte de revue. La page de paiement et l’API de reporting sont bonnes, vous faites donc Send to the merge queue pour les deux. La file contient maintenant trois éléments : le correctif CI, la page de paiement et l’API de reporting.
Midi
Le correctif CI passe sa vérification et attend l’approbation. Vous appuyez sur Land. La page de paiement est fusionnée sur le nouveau main et passe. L’API de reporting entre en conflit avec un type modifié par la page de paiement ; l’agent de résolution intervient, met à jour les appels, et la vérification passe au vert. Vous n’avez fait qu’approuver deux fois.
Après-midi
La mise à jour de dépendance est toujours rouge après deux tours de correction et est rejetée. Main reste propre. Le journal montre un changement de version majeure dans une bibliothèque, vous renvoyez donc le travail à un agent avec des instructions plus étroites.
Checklist
- Le projet a-t-il une commande de test, ou y a-t-il une commande dans Check ?
- La vérification couvre-t-elle la vérification des types et le build ?
- La Target branch est-elle la bonne ? Vide signifie la branche par défaut.
- La stratégie de fusion correspond-elle aux habitudes de votre équipe : Merge commit ou Squash ?
- Land passing branches automatically est-il activé ou désactivé volontairement ?
- Pour les dépôts GitHub, êtes-vous connecté à GitHub sur cet ordinateur ?
- Les tâches de vos agents sont-elles petites et ciblées ?
Pour conclure
Les agents parallèles sont rapides, mais une vitesse qui casse main ne dure pas. Une merge queue fusionne et teste chaque branche sur le dernier main, si bien que des branches qui passent seules ne peuvent pas casser main ensemble. Dans AgentVera, la file confie les conflits et les vérifications en échec à un agent, vérifie elle-même le résultat et, par défaut, vous laisse la décision finale.
Pour aller plus loin :
- Merge queue
- Équipe parallèle
- Git et GitHub
- Les worktrees git pour agents parallèles
- Revue de code par IA
Pour essayer AgentVera, commencez par la page d’accueil.