9 min de lecture - API de fusion asynchrone GitHub : construisez un worker, pas un bouton

Le 1er octobre 2026, GitHub a annoncé la disponibilité générale de son API de fusion asynchrone et l’a recommandée pour les fusions programmatiques de pull requests. Le point d’accès peut fusionner directement ou envoyer le travail vers une file de fusion. C’est aussi la seule API de fusion compatible avec les pull requests empilées. Un appelant envoie une requête, reçoit un identifiant, puis consulte le résultat.

Une soumission réussie ne prouve plus que le code a rejoint la branche cible. Le worker doit mémoriser sa demande, rapprocher les résultats ultérieurs et distinguer une modification mise en file d’une modification fusionnée. Traiter ce point d’accès comme une version plus lente de l’ancien appel crée de faux signaux de déploiement et des trous dans la piste d’audit.

La migration porte donc sur le workflow. L’API est prête pour la production ; votre bot ne l’est peut-être pas.

Une réponse 202 signifie « acceptée », pas « fusionnée »

L’annonce de GitHub indique que les clients envoient une requête PUT, puis interrogent le service avec l’identifiant reçu. La documentation REST définit les résultats qui comptent :

Après enqueued, il existe un second parcours jusqu’à l’état final. GitHub précise que ce résultat ne change pas lorsque la file finit par fusionner la pull request. Le worker doit alors vérifier l’état de la pull request ou consommer l’événement adéquat du dépôt. Si un tableau interne confond enqueued et merged, les notes de version, les déclencheurs de déploiement et les registres de changement peuvent devancer le code.

Enregistrez l’UUID externe avant d’accuser réception du travail dans votre propre file, avec le dépôt, le numéro de pull request, le SHA attendu, l’action, l’auteur, l’heure et l’état courant. Après un redémarrage, le worker peut reprendre sans reconstruire l’intention depuis les journaux.

Rendez la machine à états explicite

Une petite machine à états s’exploite mieux qu’un assemblage de callbacks et de reprises :

prête -> soumission -> en_attente -> fusionnée
                          |
                          +------> en_file -> observation_pr -> fusionnée
                          |
                          +------> échec -> analyse_ou_reprise

Le worker possède les transitions ; webhooks et consultations apportent les preuves. Un webhook accélère le rapprochement sans constituer l’unique chemin, car une livraison peut être tardive, dupliquée ou absente. GitHub conserve le résultat asynchrone pendant 24 heures après sa dernière mise à jour. Passé ce délai, le point d’accès renvoie 404, selon la référence de l’API.

Une première échéance alerte l’opérateur si pending dure trop longtemps. Une seconde arrête le rapprochement avant l’expiration, puis consulte directement la pull request. Ne resoumettez pas automatiquement un UUID expiré : l’opération initiale peut déjà avoir modifié le dépôt.

Il s’agit d’un problème classique de système distribué. Les conseils d’AWS sur les API idempotentes expliquent qu’une réponse absente ne permet pas de savoir si un effet de bord s’est produit. Ce guide est indépendant de GitHub, mais l’échec est identique : reprendre un appel qui modifie l’état, sans rapprochement, peut répéter le travail ou brouiller son attribution. Pour ce point d’accès, une réponse 409 peut renvoyer l’UUID et les options d’une demande de fusion déjà en attente. Conservez cette identité et continuez à l’observer au lieu de créer un second récit local pour la même pull request.

Verrouillez le code approuvé

Le corps de la requête accepte le SHA de tête attendu pour la pull request. Utilisez-le. Un relecteur peut approuver un commit, puis une automatisation tenter d’en fusionner un autre après une mise à jour de la branche. Fournir le SHA transforme cette course en conflit visible, au lieu d’élargir silencieusement l’approbation.

Conservez la même valeur dans le dossier interne. Si la tête change pendant la demande, suspendez la livraison jusqu’à comprendre l’état final. Ne remplacez pas le SHA attendu dans une boucle de reprise ; la condition de sécurité deviendrait « fusionner le contenu courant ».

Les protections de branche et les règles du dépôt déterminent toujours si la modification peut passer. GitHub documente que seul l’état élémentaire de la pull request est contrôlé lors de la soumission ; les règles sont évaluées ensuite, pendant l’exécution. Une réponse 202 accuse donc réception, elle ne rend pas un verdict de conformité aux règles.

Le scénario de gestion du code source du projet DevSecOps du NIST place la protection des branches et des fusions entre le code non approuvé et la branche principale. Gardez ce contrôle côté dépôt. Le bot demande la fusion et rapporte le résultat ; il ne recopie pas les approbations dans du code susceptible de diverger de la politique du dépôt.

GitHub indique aussi que l’API peut contourner les règles si l’appelant y est autorisé. Donnez au bot le jeton et le périmètre les plus restreints possibles, refusez ce passage dans le parcours normal et journalisez séparément toute procédure d’urgence autorisée. Le service ne doit pas contourner CODEOWNERS, les revues obligatoires ou les contrôles de sécurité.

Nos garde-fous pour le développement assisté par IA appliquent la même séparation des responsabilités aux changements générés : l’automatisation peut préparer le travail, tandis que la politique du dépôt décide de ce qui atteint la branche protégée.

L’entrée en file et la fusion ont des niveaux de service distincts

Une file ajoute une autre horloge. La demande asynchrone peut finir quand la pull request y entre, puis la file peut la reconstruire, l’éjecter ou la fusionner. Mesurez séparément l’acceptation par l’API, l’admission en file et la fusion finale.

Suivez au minimum les champs suivants :

• le délai entre soumission et état final de la demande asynchrone ;
• le délai entre admission dans la file et fusion, y compris les éjections et réadmissions ;
• les échecs classés par état initial, règle, SHA périmé, autorisation et erreur de service ;
• l’âge et le nombre de tâches dont l’état stocké diffère de celui de GitHub ;
• chaque demande de contournement, qu’elle soit tentée, refusée ou autorisée séparément.

Un « taux de réussite des fusions » unique masquerait la différence entre un bot fiable, une file saturée et un échec de règle. Les responsables doivent connaître le composant en cause avant d’agir.

Déclenchez le déploiement depuis le commit fusionné confirmé ou un événement de branche protégée, jamais depuis 202 ou enqueued. Le registre de production doit pointer vers l’OID effectivement intégré.

Une pile agrandit le périmètre d’une décision

La documentation GitHub sur l’API des pull requests empilées indique qu’une demande visant une pull request empilée inclut toutes les pull requests ouvertes situées en dessous. L’opération est atomique : le groupe admissible est fusionné ou rejoint la file ensemble, sinon rien ne change. Les règles sont évaluées plus tard et un échec revient dans le résultat asynchrone.

L’API de fusion asynchrone est disponible pour tous, mais la fonction de pull requests empilées reste en préversion publique lors de notre revue du 2 octobre. Séparez ces cycles de vie dans la décision de déploiement. Une équipe peut migrer les fusions ordinaires vers le nouveau point d’accès sans activer les piles.

Si les piles entrent dans le périmètre, l’écran d’approbation et l’audit doivent montrer tout l’ensemble inférieur ainsi que la pull request nommée dans l’URL. Conservez chaque numéro, SHA, position et état de revue afin que l’opérateur voie toutes les modifications couvertes.

Débutez par des pull requests indépendantes sur un dépôt à faible risque. Testez ensuite une branche protégée, un SHA périmé, une pull request en brouillon, une demande déjà en cours, l’entrée en file et un échec forcé de règle. Exercez le redémarrage du worker pendant pending, la livraison tardive d’un webhook et l’expiration du résultat. N’ajoutez les piles qu’après avoir obtenu des états et des audits fiables.

Le contrat de migration de l’équipe plateforme

Avant de modifier le bot de production, rédigez le contrat que les équipes produit et exploitation pourront inspecter :

1. La source de l’intention de fusion et les personnes autorisées à la créer.
2. La pull request exacte, son SHA de tête, l’action demandée et la politique de dépôt applicable.
3. La méthode utilisée par le worker pour stocker l’UUID, consulter, recevoir les événements et rapprocher les écarts.
4. Les états autorisés à déclencher une livraison, un déploiement, une notification ou un incident.
5. Les limites de reprise, le traitement de l’expiration, la récupération manuelle et les preuves conservées.
6. Le statut des pull requests empilées : exclues, testées ou acceptées avec visibilité sur tout l’ensemble.

Faites fonctionner les deux observateurs côte à côte, sans autoriser le nouveau worker à fusionner. Comparez les pull requests jugées admissibles, puis activez quelques dépôts avec un arrêt manuel. La migration est terminée quand le worker sait reprendre et prouver l’état final, pas lors du premier 202.

L’approche de services d’Exceev relie politique de livraison, ingénierie et transfert de compétences. Une petite équipe peut retenir un worker éphémère adossé à une table durable. Le test reste le même : sait-il reprendre, rapprocher et expliquer chaque décision de fusion ?

Sources et limites

Nous avons ouvert et vérifié chaque source ci-dessous le 2 octobre 2026.

• L’annonce de GitHub du 1er octobre établit la disponibilité générale, le flux asynchrone et la recommandation pour les fusions programmatiques.
• La référence REST des pull requests définit champs, codes, états, conservation pendant 24 heures et différence entre enqueued et merged.
• La documentation des pull requests empilées documente leur préversion, la portée sur les éléments inférieurs, l’évaluation ultérieure des règles et le résultat atomique.
• L’article d’AWS sur les API idempotentes traite indépendamment des reprises, résultats incertains et effets de bord.
• Le scénario DevSecOps du NIST apporte un guide indépendant sur la revue approuvée et l’application des protections de branche et de fusion.

Nous n’avons ni appelé le point d’accès, ni mesuré une file, ni vérifié l’abonnement d’une organisation. GitHub peut modifier comportement, autorisations, préversion et documentation. Ces exemples ne décrivent ni Exceev ni un client. Validez chez vous le jeton, les règles, les webhooks, les traces et le retour arrière.