# 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.

> [!NOTE]
> 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](https://gh.io/event-streams-signup) 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](https://cli.github.com/) (`gh`) pour les appels d’API et `curl` pour le flux.

### 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.

```shell
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 `id`l’abonnement , `expires_at`et `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`:

```shell
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 :

```shell
gh api -X DELETE /event-subscriptions/ID
```

## Référence d’API

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

| Method | Route | Description |
| --- | --- | --- |
| `POST` | `/event-subscriptions` | Créez un abonnement. |
| `GET` | `/event-subscriptions` | Ré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}/events` | Diffusez 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 Content`et 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](https://cloudevents.io/) 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_url`et `status`.

| Status | Procédure à suivre |
| --- | --- |
| `400` | Le corps de la requête n’est pas un objet JSON. Corrigez la requête. |
| `401` | Votre jeton n’est pas valide ou a expiré. Actualisez-le et réessayez une fois. |
| `403` | Les 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. |
| `404` | L’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. |
| `503` | Temporaire. Réessayez après le nombre de secondes dans l’en-tête `Retry-After` . |
| `500`, `504` | Ré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.
* **Pas de replay :** consultez [Gestion du flux](#handling-the-stream).

## Commentaires

Nous aimerions entendre ce qui fonctionne et ce qui n’est pas. Partagez vos commentaires dans la [discussion de la communauté GitHub](https://github.com/orgs/community/discussions/211595).