Gestion d’une file d’attente de fusion

Vous pouvez augmenter la vitesse de développement avec une file d’attente de fusion pour les demandes de tirage dans votre référentiel.

Qui peut utiliser cette fonctionnalité ?

People with admin permissions can manage merge queues for pull requests targeting selected branches of a repository.

Les files d’attente de fusion de demandes de tirage (pull requests) sont disponibles dans n’importe quel dépôt public appartenant à une organisation ou dans les dépôts privés appartenant aux organisations utilisant GitHub Enterprise Cloud. Pour plus d’informations, consultez « Plans de GitHub ».

Dans cet article

À propos des files d’attente de fusion

Une file d’attente de fusion permet d’augmenter la vitesse en automatisant les fusions de demandes de tirage dans une branche occupée et en veillant à ce que la branche ne soit jamais interrompue par des modifications incompatibles.

La file d’attente de fusion offre les mêmes avantages que la protection de branche Exiger que les branches soient à jour avant de fusionner, mais ne nécessite pas qu’un auteur de demande de tirage mette à jour sa branche de demande de tirage et attende que les vérifications d'état se terminent avant d’essayer de fusionner.

L’utilisation d’une file d’attente de fusion est particulièrement utile sur les branches qui ont un nombre relativement élevé de demandes de tirage qui fusionnent chaque jour de nombreux utilisateurs différents.

Dès qu’une demande de tirage a réussi toutes les vérifications de protection de branche nécessaires, un utilisateur avec un accès en écriture au référentiel peut ajouter cette demande de tirage à une file d’attente de fusion. La file d’attente de fusion garantit que les modifications de la demande de tirage passent toutes les vérifications d'état requises lorsqu’elles sont appliquées à la dernière version de la branche cible et aux demandes de tirage déjà dans la file d’attente.

Une file d’attente de fusion peut utiliser GitHub Actions ou votre propre fournisseur de CI pour exécuter les vérifications requises sur les demandes de tirage dans une file d’attente de fusion. Pour plus d’informations, consultez « Documentation GitHub Actions ».

Pour plus d’informations sur la fusion d’une demande de tirage à l’aide d’une file d’attente de fusion, consultez « Fusion d’une demande de tirage avec une file d’attente de fusion ».

Configuration des workflows d’intégration continue (CI) pour les files d’attente de fusion

Remarques :

  • Une file d’attente de fusion ne peut pas être activée avec des règles de protection de branche qui utilisent des caractères génériques (*) dans le modèle de nom de branche.
  • Une file d’attente de fusion attend que les vérifications requises soient signalées avant de pouvoir poursuivre la fusion. Vous devez mettre à jour votre configuration CI pour déclencher et signaler des événements de groupe de fusion lorsque vous avez besoin d’une file d’attente de fusion.
  • Les vérifications de fusion de files d’attente et de demandes de tirage (pull request) sont couplées et configurées sous des règles de protection de branche ou des ensembles de règles. Pour plus d’informations, consultez « Gestion d’une file d’attente de fusion ».

Déclenchement de vérifications de groupe de fusion avec GitHub Actions

Vous devez utiliser l’événement merge_group pour déclencher votre workflow GitHub Actions quand une demande de tirage (pull request) est ajoutée à une file d’attente de fusion.

Remarque : Si votre référentiel utilise GitHub Actions pour effectuer des vérifications requises sur les demandes de tirage dans votre référentiel, vous devez mettre à jour les workflows pour inclure l’événement merge_group en tant que déclencheur supplémentaire. Autrement, les vérifications d’état ne seront pas déclenchées lorsque vous ajouterez une demande de tirage à une file d’attente de fusion. La fusion échouera, car la vérification d’état requise ne sera pas signalée. L’événement merge_group est distinct des événements pull_request et push.

Voici comment se présente un workflow qui signale une vérification requise par les protections de la branche cible :

on:
  pull_request:
  merge_group:

Pour plus d’informations sur l’événement merge_group, consultez « Événements qui déclenchent des flux de travail ».

Déclenchement de vérifications de groupes de fusion avec des fournisseurs de CI tiers

Avec des fournisseurs de CI tiers, vous devrez peut-être mettre à jour votre configuration de CI pour permettre l’exécution quand une branche commençant par le préfixe spécial gh-readonly-queue/{base_branch} est envoyée. Il s’agit des branches temporaires qui sont créées en votre nom par une file d’attente de fusion et qui contiennent une autre sha de la demande de tirage.

Gestion d’une file d’attente de fusion

Les administrateurs de référentiel peuvent exiger une file d’attente de fusion en activant le paramètre de protection de branche « Exiger une file d’attente de fusion » dans les règles de protection de la branche de base. Pour plus d’informations, consultez « Gestion d’une règle de protection de branche ».

Une fois que vous avez activé le paramètre « Exiger une file d’attente de fusion », vous pouvez également accéder aux paramètres suivants :

  • Méthode de fusion : Sélectionnez la méthode à utiliser lors de la fusion des demandes de tirage en file d’attente : fusionner, rebaser ou squash.

  • Concurrence de build : nombre maximal de webhooks merge_group à distribuer (entre 1 et 100), limitant la quantité totale de builds CI concurrentes. Cela affecte la vitesse des fusions qu’une file d’attente de fusion peut effectuer.

  • Fusionner uniquement les demandes de tirage non défaillantes : ce paramètre détermine comment une file d’attente de fusion forme les groupes de demandes de tirage à fusionner.

    Activé ?Description
    OuiToutes les demandes de tirage doivent satisfaire aux vérifications requises pour être fusionnées.
    NonLes demandes de tirage qui ont échoué aux vérifications requises peuvent être ajoutées à un groupe tant que la dernière demande de tirage du groupe a réussi les vérifications requises. Si la dernière demande de tirage du groupe a réussi les vérifications requises, cela signifie que les vérifications ont réussi pour l’ensemble combiné de modifications dans le groupe de fusion. Laisser cette case décochée peut être utile si vous rencontrez des échecs de test intermittents, mais que vous ne souhaitez pas que les faux négatifs suspendent la file d’attente.

  • Délai d’expiration des vérifications d’état : Choisissez la durée pendant laquelle la file d’attente doit attendre une réponse de CI avant de supposer que les vérifications ont échoué.

  • Limites de fusion : sélectionnez le nombre minimal et le nombre maximal de demandes de tirage à fusionner dans la branche de base (entre 1 et 100), ainsi qu’un délai d’expiration après lequel la file d’attente doit cesser d’attendre d’autres entrées et fusionner avec moins de demandes de tirage que le nombre minimal.

Remarque : Les limites de fusion ne combinent pas les builds merge_group. Les limites de fusion affectent uniquement les fusions dans la branche de base une fois qu’un ou plusieurs merge_group ont satisfait aux vérifications de build.

Limite de fusionCas d’usage
Nombre maximal de demandes de tirage à fusionnerVous pouvez spécifier une taille de groupe maximale, ce qui est utile si des fusions dans votre branche de base déclenchent un déploiement et que vous souhaitez vous assurer que vous ne déployez pas trop de modifications à la fois.
Nombre minimal de demandes de tirage à fusionnerVous pouvez spécifier une taille de groupe minimale, ce qui est utile si les fusions dans votre branche de base déclenchent un processus de génération ou de déploiement d’intégration continue et que vous ne souhaitez pas conserver les entrées suivantes dans la file d’attente.
Temps d’attenteVous pouvez spécifier un délai d’attente pour atteindre la taille minimale du groupe, ce qui permet aux groupes plus petits de fusionner s’il n’y a plus de demandes de tirage en file d’attente dans la limite de temps spécifiée.

Fonctionnement des files d’attente de fusion

À mesure que les demandes de tirage sont ajoutées à la file d’attente de fusion, celle-ci garantit qu’elles sont fusionnées dans un ordre de premier entré, premier sorti où les vérifications requises sont toujours satisfaites.

La file d’attente de fusion crée des branches temporaires avec un préfixe spécial pour valider les modifications de demande de tirage (pull request). Lorsqu’une demande de tirage est ajoutée à la file d’attente de fusion, les modifications apportées à la demande de tirage sont regroupées dans un merge_group avec la dernière version du base_branch, ainsi que les modifications des demandes de tirage avant celle-ci dans la file d’attente. GitHub fusionne toutes ces modifications dans base_branch une fois que les vérifications requises par les protections de branche de base_branch ont réussi.

Pour obtenir des informations sur les méthodes de fusion, consultez « À propos des fusions de demande de tirage ».

CI réussie

Lorsque plusieurs demandes de tirage sont ajoutées à la file d’attente de fusion et que les branches temporaires merge_group ont des résultats de CI réussie, elles sont toutes deux fusionnées. Dans le scénario suivant, deux demandes de tirage sont correctement ajoutées à la file d’attente et fusionnées dans la branche cible.

  1. L’utilisateur ajoute la demande de tirage #1 à la file d’attente de fusion.
  2. La file d’attente de fusion crée une branche temporaire avec le préfixe de main/pr-1 qui contient les modifications de code à partir de la branche cible et de la demande de tirage #1. Un événement webhook merge_group de type checks_requested est distribué et la file d’attente de fusion attend une réponse de votre fournisseur CI.
  3. L’utilisateur ajoute la demande de tirage #2 à la file d’attente de fusion.
  4. La file d’attente de fusion crée une branche temporaire avec le préfixe de main/pr-2 qui contient les modifications de code à partir de la branche cible, de la demande de tirage #1 et de la demande de tirage (pull request) #2 et distribue les webhooks.
  5. Lorsque l’API GitHub reçoit des réponses de CI réussie pour les branches merge_group main/pr-1 et main/pr-2, la branche temporaire main/pr-2 est fusionnée dans la branche cible. La branche cible contient désormais les deux modifications des demandes de tirage #1 et #2.

Échec de l’intégration continue

Après le regroupement d’une demande de tirage avec la dernière version de la branche cible et les changements qui la précèdent dans la file d’attente, si les vérifications d’état nécessaires échouent ou qu’il y a des conflits avec la branche de base, la demande de tirage (pull request) est supprimée de la file d’attente. La chronologie de la demande de tirage affiche la raison pour laquelle elle a été supprimée de la file d’attente.

Le scénario suivant décrit ce qui se passe lorsqu’une intégration continue signale un état d’échec à propos d’une demande de tirage.

  1. L’utilisateur ajoute la demande de tirage #1 à la file d’attente de fusion.
  2. La file d’attente de fusion crée une branche temporaire avec le préfixe de main/pr-1 qui contient les modifications de code à partir de la branche cible et de la demande de tirage #1. Un événement webhook merge_group de type checks_requested est distribué et la file d’attente de fusion attend une réponse de votre fournisseur CI.
  3. L’utilisateur ajoute la demande de tirage #2 à la file d’attente de fusion.
  4. La file d’attente de fusion crée une branche temporaire avec le préfixe de main/pr-2 qui contient les modifications de code à partir de la branche cible, de la demande de tirage #1 et de la demande de tirage (pull request) #2 et distribue les webhooks.
  5. Lorsque l’API GitHub reçoit un état d’échec pour main/pr-1, la file d’attente de fusion supprime automatiquement la demande de tirage #1 de la file d’attente de fusion.
  6. La file d’attente de fusion crée une branche temporaire avec le préfixe de main/pr-2 pour qu’elle ne contienne que les modifications de code à partir de la branche cible et de la demande de tirage #2.
  7. Lorsque l’API GitHub reçoit des réponses de CI réussie pour les branches merge_group``main/pr-2, la branche temporaire main/pr-2 est fusionnée dans la branche cible sans inclure la demande de tirage (pull request) #1.

Il existe plusieurs raisons pour lesquelles une demande de tirage peut être supprimée d’une file d’attente de fusion :

  • le service de CI configuré signale des échecs de test pour un groupe de fusion
  • l’expiration du délai d’attente d’un résultat de CI réussie en fonction du paramètre de délai d’expiration configuré
  • l’utilisateur demande une suppression via l’API ou l’interface de file d’attente de fusion
  • échec de la protection de branche qui n’a pas pu être résolu automatiquement

Saut vers le haut de la file d’attente

Lors de l’ajout d’une demande de tirage à une file d’attente de fusion, il existe une option permettant de déplacer votre demande de tirage vers le haut de la file d’attente.

Remarque : n’oubliez pas que le saut vers le haut d’une file d’attente de fusion entraîne une régénération complète de toutes les demandes de tirage en cours, car la réorganisation de la file d’attente introduit une interruption dans le graphique de validation. L’utilisation intensive de cette fonctionnalité peut ralentir la vitesse des fusions pour votre branche cible.

Le scénario suivant décrit ce qui se passe lorsqu’un utilisateur saute la file d’attente.

  1. L’utilisateur ajoute la demande de tirage #1 à la file d’attente de fusion.
  2. La file d’attente de fusion crée une branche temporaire avec le préfixe de main/pr-1 qui contient les modifications de code à partir de la branche cible et de la demande de tirage #1. Un événement webhook merge_group de type checks_requested est distribué et la file d’attente de fusion attend une réponse de votre fournisseur CI.
  3. L’utilisateur ajoute la demande de tirage #2 à la file d’attente de fusion.
  4. La file d’attente de fusion crée une branche temporaire avec le préfixe de main/pr-2 qui contient les modifications de code à partir de la branche cible, de la demande de tirage #1 et de la demande de tirage (pull request) #2 et distribue les webhooks.
  5. L’utilisateur ajoute la demande de tirage #3 à la file d’attente de fusion avec l’option de saut qui introduit une interruption dans le graphique de validation.
  6. La file d’attente de fusion crée une branche temporaire avec le préfixe de main/pr-3 qui contient les modifications de code à partir de la branche cible et de la demande de tirage #3 et distribue les webhooks.
  7. La file d’attente de fusion recrée les branches temporaires avec le préfixe de main/pr-1 et main/pr-2 qui contiennent les modifications de la demande de tirage #3, et distribue les webhooks.

Pour aller plus loin