Skip to main content
Skip to content

Utilisation de flux d’événements GitHub

GitHub Les flux d’événements permettent aux agents et aux intégrations de s’abonner à des modifications sur une ressource au lieu d’interroger pour eux.

Remarque

GitHub Les flux d’événements sont en préversion publique préversion et peuvent être modifiés. Nous pouvons apporter des changements incompatibles à l’API, aux types d’événements et aux limites avec un bref préavis pendant la préversion.

À propos de GitHub Event Streams

GitHub Les flux d’événements permettent aux agents et aux intégrations de s’abonner à des modifications sur une ressource au lieu de les interroger régulièrement. Il prend actuellement en charge les événements pour les pull requests.

Vous créez un abonnement pour une pull request une fois, maintenez un flux ouvert sur celle-ci et GitHub vous envoie un événement lorsque quelque chose auquel vous êtes abonné change. Votre client peut ensuite récupérer l’état le plus récent à partir de l’API REST.

Les événements sont transmis via Server-Sent Events (SSE), de sorte que votre client n’a pas besoin d’un point de terminaison public, comme c’est le cas avec les webhooks. Cela permet aux flux d’événements d’être adaptés aux agents et aux outils s’exécutant sur l’ordinateur d’un développeur.

Event Streams n’est disponible que sur GitHub.com. Ce n’est pas encore disponible sur GHE.com.

Avant de commencer

  • Accès : nous déployons cette fonctionnalité sur liste d’attente. Pour rejoindre la liste d’attente, remplissez le formulaire de liste d’attente et nous vous contacterons lorsque votre compte a été autorisé à accéder. Nous allons activer les flux d’événements par compte :

    • Pour les jetons utilisateur, nous activons votre compte d’utilisateur.
    • Pour les jetons d’installation GitHub App, nous activons l’utilisateur, l’organisation ou l’entreprise sur laquelle l’application est installée. Cela couvre chaque application installée là, y compris les GITHUB_TOKEN dans GitHub Actions, mais pas les propres jetons d’utilisateur des membres.

    Les demandes d’autres comptes retournent 403 Forbidden avec le message « Les abonnements aux événements ne sont pas activés pour ce compte ».

  • Jeton : utilisez un jeton d’utilisateur (un personal access token, un jeton OAuth ou un GitHub App jeton d’accès utilisateur) ou un GitHub App jeton d’accès d’installation. Les applications s’authentifiant comme elles-mêmes ne sont pas prises en charge.

  • Autorisations : l’utilisateur ou l’installation a besoin d’un accès en lecture à la pull request auquel vous vous abonnez.

Quickstart

Ces exemples utilisent le GitHub CLI (gh) pour les appels d’API et curl pour le flux. Vous pouvez donc voir chaque étape de l’API. Si vous utilisez GitHub CLI la version 2.105.0 ou ultérieure, les commandes gh event gèrent l’abonnement, la diffusion en continu et la reconnexion pour vous. Consultez l’utilisation des commandes GitHub CLI.

1. Créer un abonnement

Remplacez OWNER, REPO et NUMBER par le propriétaire, le nom du référentiel et le numéro de la pull request.

EVENTS_URL=$(gh api -X POST /event-subscriptions \
  -f resource_url=https://github.com/OWNER/REPO/pull/NUMBER \
  -f 'event_types[]=com.github.pull_request.review.submitted.v1' \
  -f 'event_types[]=com.github.pull_request.state.changed.v1' \
  --jq .events_url)

La réponse inclut les éléments de idl’abonnement , expires_atet events_url. L’option --jq .events_url imprime uniquement events_url, dont vous avez besoin à l’étape suivante. Un nouvel abonnement retourne 201 Created. Si vous disposez déjà d’un abonnement avec les mêmes types de demandes de tirage et d’événements, vous récupérez cet abonnement avec 200 OK.

2. Ouvrir le flux d’événements

Ouvrez le flux à l’adresse events_url. gh api attend l’ensemble de la réponse avant d’imprimer quoi que ce soit. Utilisez donc un client de streaming comme curl -N:

curl -sS -N -H 'Accept: text/event-stream' \
  -H @<(printf 'Authorization: Bearer %s' "$(gh auth token --hostname github.com)") \
  "$EVENTS_URL"

Ouvrez le flux avant de déclencher l’activité que vous souhaitez voir. Le flux transmet uniquement les événements qui se produisent pendant son ouverture.

3. Récupérer l’état le plus récent

Chaque événement indique qu’une modification s’est produite et fournit un api_url. Récupérez api_url avec votre jeton pour lire l’état actuel de la revue ou de la pull request.

4. Supprimer l’abonnement

Une fois que vous avez terminé, fermez le flux. Supprimer un abonnement ne ferme pas ses flux ouverts, donc fermez le flux vous-même d’abord. Répertoriez vos abonnements gh api /event-subscriptions actifs pour rechercher les abonnements .id Supprimez ensuite l’abonnement, en remplaçant ID par cette valeur :

gh api -X DELETE /event-subscriptions/ID

Utilisation des commandes GitHub CLI

GitHub CLI 2.105.0 et versions ultérieures incluent gh event des commandes pour les flux d’événements. Ces commandes sont également dans préversion publique et peuvent être modifiées.

Pour attendre un événement sur une demande de tirage, exécutez gh event listen avec l’URL de la demande de tirage et un ou plusieurs types d’événements :

gh event listen --resource https://github.com/OWNER/REPO/pull/NUMBER \
  --event com.github.pull_request.review.submitted.v1,com.github.pull_request.state.changed.v1

gh event listen crée un abonnement ou réutilise votre abonnement existant pour la même pull request et les mêmes types d’événement. Il ouvre ensuite le flux et imprime chaque événement sous la forme d’une ligne JSON. Il se reconnecte lorsque le flux est interrompu et crée à nouveau l’abonnement s’il expire.

  • Par défaut, la commande s’arrête après le premier événement. Cela convient aux agents, qui attendent généralement qu’une commande se termine avant de continuer.
  • --count N s’arrête après N événements et --follow continue d’écouter jusqu’à ce que vous l’arrêtiez.
  • --timeout arrête d’attendre après une durée telle que 30m, et quitte avec le code de statut 8.
  • --jq et --template mettent en forme chaque événement, comme avec gh api. Par exemple, --jq .data.conclusion imprime uniquement la conclusion d’une suite de vérifications.

La commande imprime Listening for events. sur stderr une fois le flux ouvert. Les modifications apportées avant ne sont pas signalées. Lisez donc l’état actuel de la pull request après avoir vu cette ligne.

Pour gérer directement les abonnements, utilisez gh event subscription list, create, view et delete. gh event listen ne supprime pas son abonnement lorsqu’il se ferme. Les abonnements expirent après 24 heures.

Lorsque gh détecte qu’un agent l’appelle, des commandes telles que gh pr create, gh pr view, gh run view, gh run watch et gh api suggèrent gh event listen au lieu du scrutage.

Pour toutes les options, exécutez gh event listen --help.

Référence d’API

Tous les itinéraires se trouvent sur https://api.github.com.

MethodRouteDescription
POST/event-subscriptionsCréez un abonnement.
GET/event-subscriptionsRépertoriez vos abonnements actifs, du plus récent au plus ancien.
GET/event-subscriptions/{subscription_id}Obtenez un abonnement.
DELETE/event-subscriptions/{subscription_id}Supprimer une subscription.
GET/event-subscriptions/{subscription_id}/eventsDiffusez en continu les événements de l’abonnement sur SSE.

Création d’un abonnement

Le corps de la requête comporte deux champs :

  • resource_url: l’URL web de la pull request, sous la forme https://github.com/OWNER/REPO/pull/NUMBER, ou son URL d’API REST, sous la forme https://api.github.com/repos/OWNER/REPO/pulls/NUMBER, sans chemin supplémentaire, requête ou fragment. Les deux formulaires nomment le même abonnement, et la réponse retourne toujours l’URL web. Les URL d’une partie d’une pull request (par exemple, une review) ne sont pas acceptées.
  • event_types: un ou plusieurs des types d’événements. Les types d’événements inconnus retournent 422 Unprocessable Contentet le message d’erreur les nomme.

Les réponses d’abonnement incluent id, event_types, created_at, resource_url, expires_at, url et events_url.

Limits

  • Un abonnement couvre une pull request.
  • Les abonnements expirent 24 heures après leur création. Pour continuer à recevoir des événements, créez un abonnement.
  • Chaque utilisateur, application et jeton d’installation peut avoir jusqu’à 100 abonnements actifs. En créer davantage renvoie 422 avec le message « Limite d’abonnement dépassée ». Supprimez les abonnements dont vous n’avez plus besoin.

Types d’événements

| Type d’événement | Envoyé quand | api_url pointe vers | | --- | --- | --- | | com.github.pull_request.check_suite.status.changed.v1 | Une suite de vérifications sur le commit de tête de la pull request se termine, quelle que soit sa conclusion. | La suite de vérifications | | com.github.pull_request.head.changed.v1 | Les changements du commit de tête de la pull request, par exemple après un push. | La pull request | | com.github.pull_request.merge_conflict.v1 | GitHub indique que la pull request a un conflit de fusion. | La pull request | | com.github.pull_request.review.submitted.v1 | Quelqu’un soumet une révision qui approuve les modifications, demande des changements ou ajoute des commentaires. | La revue | | com.github.pull_request.state.changed.v1 | La demande de fusion est fusionnée, fermée, rouverte, marquée comme prête à être examinée ou convertie en brouillon. | La pull request |

Une pull request comporte généralement plusieurs suites de vérification, une par application, de sorte qu’une transmission (push) peut produire plusieurs événements de suite de vérification, et une réexécution en produit un autre lorsqu’elle se termine.

Chaque commentaire de révision unique et chaque réponse à un commentaire de révision comptent également comme révision.

Les événements vous indiquent actuellement que quelque chose a changé, pas ce qui a changé. Par exemple, un événement de révision n’inclut pas l’état de la révision et un événement de modification d’état ne indique pas si la demande de tirage a été fusionnée ou fermée. Récupérez api_url pour le savoir.

Les événements de la suite de vérification sont l’exception : leur champ data.conclusion est toujours présent. Vous pouvez donc distinguer la réussite de l’échec sans récupération. Il s’agit de l’un des éléments suivants : success, startup_failure, timed_out, neutral, failure, action_required, stale, cancelled, skipped ou unknown (une conclusion en dehors de cette liste).

GitHub vérifie uniquement les conflits de fusion après qu’une personne consulte ou récupère la pull request. Par conséquent, les événements de conflit de fusion peuvent prendre plus de temps à arriver que d’autres événements.

Format d’événement

Chaque événement du flux comporte trois champs :

  • id: ID de l’événement
  • event: le type d’événement
  • data: l’événement complet sous la forme d’un CloudEvent JSON sur une seule ligne

Gestion du flux

Les flux d’événements sont des connexions de longue durée. Votre client doit donc gérer les lacunes, les événements répétés ou hors commande et les flux qui se terminent. Suivez ces pratiques pour éviter de manquer des événements ou de mal les gérer.

  • Événements manqués : les flux fournissent des événements uniquement lorsqu’ils sont ouverts, sans rejeu. Vous ne recevrez pas d’événements qui se produisent :

    • Avant d’ouvrir le flux
    • Pendant une courte fenêtre immédiatement après avoir créé l’abonnement
    • Pendant que vous êtes déconnecté

    Après vous être abonné, récupérez une fois la pull request pour récupérer tout ce que vous avez manqué.

  • Doublons et ordre : vous pouvez recevoir le même événement plusieurs fois, et les événements d’une pull request peuvent arriver dans le désordre. Récupérez l’état actuel depuis api_url au lieu de compter sur l’ordre des événements. Pour les événements de révision et de suite de vérification, api_url identifie la suite de révision ou de vérification, afin de pouvoir l’utiliser pour dédupliquer.

  • Pulsations : pendant que le flux est inactif, le serveur envoie une ligne de commentaire commençant par : dans les 15 secondes du dernier événement ou commentaire. Ignorez ces lignes.

  • Fin d’un flux : lorsque le serveur met fin à un flux, son dernier événement est github.stream.end, avec un outcome in data. Agir sur outcome, et non sur le champ facultatif reason , car de nouvelles reason valeurs peuvent être ajoutées.

    • subscription_ended : l’abonnement a expiré ou vous avez perdu l’accès à la pull request. Arrêtez le flux et créez un nouvel abonnement si vous en avez besoin.
    • reconnect: rouvrez le flux sur le même abonnement. Appliquez un délai exponentiel avec gigue, et actualisez d’abord votre jeton s’il a pu expirer.
  • Déconnexions inattendues : si un flux se termine sans événement github.stream.end, reconnectez-vous.

  • Jetons d’installation : les jetons d’installation expirent après une heure, et les flux ouverts prennent fin lors de la prochaine vérification d’accès après leur expiration. Créez un nouveau jeton avant de vous reconnecter. Un GITHUB_TOKEN ne peut pas être renouvelé, alors supprimez les abonnements qu’il a créés avant la fin de la tâche.

Errors

Les réponses d’erreur incluent message, documentation_urlet status.

StatusProcédure à suivre
400Le corps de la requête n’est pas un objet JSON. Corrigez la requête.
401Votre jeton n’est pas valide ou a expiré. Actualisez-le et réessayez une fois.
403Les flux d’événements ne sont pas activés pour ce compte, ou vous vous authentifiez en tant qu’application plutôt qu’en tant qu’utilisateur ou installation. Ne réessayez pas.
404L’abonnement n’existe pas, a expiré ou appartient à un autre utilisateur, ou vous ne pouvez pas accéder à la pull request. Ne réessayez pas.
422
resource_url ou event_types n’est pas valide, ou vous avez atteint la limite d’abonnements. Corrigez la demande ou supprimez les abonnements dont vous n’avez plus besoin.
503Temporaire. Réessayez après le nombre de secondes dans l’en-tête Retry-After .
500, 504Réessayez avec temporisation croissante.

Limitations connues

  • Aucun événement « tous les contrôles terminés » : vous obtenez un événement par suite de vérifications. Pour savoir si toutes les vérifications sont effectuées, récupérez les suites de vérifications de la demande de tirage après chaque événement.
  • Commentaires de la conversation de la pull request : les commentaires dans l’onglet de conversation de la pull request ne produisent pas encore d’événements. Les commentaires de révision, eux aussi, génèrent des événements de révision.
  • Flux ouverts après suppression : la suppression d’un abonnement ne ferme pas encore ses flux ouverts. Fermez le flux vous-même avant de supprimer l’abonnement.
  • États de validation : les événements de la suite de vérification ne couvrent pas les états de validation créés avec l’API REST. Si les vérifications requises d’une pull request incluent des statuts de commit, récupérez-les séparément.
  • Pas de relecture : consultez Gestion du flux.

Commentaires

Nous aimerions entendre ce qui fonctionne et ce qui n’est pas. Partagez vos commentaires dans la discussion de la communauté GitHub.