# Webhooks et flux de travail du statut des tickets

Utilisez des webhooks et GitHub Actions des flux de travail pour répondre lorsque l’état d’un problème change.

> [!NOTE]
> Les états des problèmes figurent dans aperçu et disponibles uniquement pour les comptes inscrits dans la préversion. Les charges utiles webhook et le `status_changed` type d’activité sont susceptibles de changer.

## À propos des événements de modification d’état

Lorsque l’état d’un problème change, GitHub envoie un `issues` événement webhook avec l’action `status_changed` . Les payloads pour chaque `issues` action incluent également l’état actuel du ticket dans `issue.status`. Vous pouvez utiliser ces événements pour synchroniser d’autres outils avec vos problèmes ou pour exécuter un GitHub Actions flux de travail lorsqu’un problème atteint un état particulier.

Les statuts sont inclus uniquement pour les tickets dans les dépôts qui utilisent des statuts de ticket. Pour les autres issues, les payloads n’incluent pas `issue.status`, et GitHub n’envoie pas `status_changed`.

Pour le schéma complet de la charge utile, consultez [Événements et charges utiles du webhook](/fr/webhooks/webhook-events-and-payloads?actionType=status_changed#issues).

## Objets de statut

Les payloads de webhook décrivent chaque état avec un objet qui a trois propriétés.

| Propriété  | Catégorie | Description                                                                                                                                                      |
| ---------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | Integer   | Identificateur du statut.                                                                                                                                        |
| `name`     | String    | Nom d’affichage de l’état, tel que `In progress`. Le nom peut changer.                                                                                           |
| `category` | String    | Catégorie de l’état, telle que `backlog`, `started`, `planned`, `completed`, `not_planned` ou `duplicate`. D’autres catégories peuvent être ajoutées à l’avenir. |

Plusieurs états peuvent appartenir à la même catégorie. Par exemple, en cours et en revue appartiennent tous deux à la catégorie `started`. Pour faire correspondre un état dans votre code ou flux de travail, utilisez son `id`. Pour faire correspondre tous les statuts d’une catégorie, utilisez son `category`. Ne faites pas correspondre `name`.

`issue.status` est `null` lorsque le ticket n’a pas d’état. Par exemple, un problème créé avant que les états ne soient disponibles dans son référentiel n’a pas d’état tant que quelqu’un n’en définit pas un, ou jusqu’à ce que le problème soit fermé ou rouvert.

## La charge utile `status_changed`

En plus de `issue`, `repository`, `sender` et des autres propriétés que chaque `issues` charge inclut, une `status_changed` charge inclut les propriétés suivantes. Pour cette action, `sender` est la personne ou l’application qui a modifié l’état.

| Propriété                                                                                                                                                                                                                                                                                                                             | Description                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `status`                                                                                                                                                                                                                                                                                                                              | État vers lequel le ticket a été changé.                                          |
| `changes.status.from`                                                                                                                                                                                                                                                                                                                 | L’état qu’avait le problème avant la modification, ou `null` s’il n’en avait pas. |
| `changes.state.from`                                                                                                                                                                                                                                                                                                                  |                                                                                   |
| Le `state` précédent du problème, `open` ou `closed`. Uniquement inclus lorsque le changement d’état a également fermé ou rouvert le problème.                                                                                                                                                                                        |                                                                                   |
| `changes.state_reason.from`                                                                                                                                                                                                                                                                                                           |                                                                                   |
| L’`state_reason` précédent du ticket. Inclus uniquement lorsque le changement d’état a également changé la raison de l’état, par exemple en fermant ou en rouvrant le problème, ou en modifiant la raison de sa fermeture. C’est `null` quand le ticket n’a pas eu de raison de l’état, par exemple la première fois qu’il est fermé. |                                                                                   |

### Valeurs capturées et ticket actuel

Les propriétés `status` et `changes` décrivent la modification au moment de son enregistrement. La propriété `issue`, y compris `issue.status`, décrit le ticket lors de la création de la livraison, comme pour toute autre action `issues`. Si le problème change à nouveau d’ici là, `issue.status` peut différer de `status`. Par exemple, si quelqu’un déplace un problème de En cours à En révision, puis rapidement vers Terminé, la livraison pour la première modification peut avoir un `issue.status` de Terminé.

Pour savoir ce qu’a fait un changement particulier, utilisez `status` et `changes`. Une charge utile différée, retentée ou livrée de nouveau peut être obsolète. `issue.status` peut donc ne pas refléter l’état le plus récent du problème. Pour plus d’informations, consultez [Livraison](#delivery), plus loin dans cet article.

## Quand `status_changed` est envoyé

GitHub envoie `status_changed` chaque fois que l’état d’un problème change, y compris les modifications apportées GitHub lorsqu’un problème est créé, fermé ou rouvert.

* **Définition d’un état** : une personne choisit un autre état pour une issue.
* **Création d’un ticket** : un nouveau ticket obtient l’état backlog, sauf si la personne qui le crée choisit un autre état.
  `changes.status.from` a la valeur `null`.
  GitHub envoie `opened` ainsi que `status_changed`.
* **Définition d’un premier état** : un problème existant sans état en obtient un.
  `changes.status.from` a la valeur `null`.
* **Fermeture ou réouverture d’un problème** : Fermer un problème comme terminé définit l’état Terminé, le fermer comme non planifié définit l’état Non planifié, et le fermer comme doublon définit l’état Doublon. La réouverture d’un problème sans choisir de statut définit le statut Backlog.
  GitHub envoie `closed` ou `reopened` aussi bien que `status_changed`.
* **Lier une pull request** : le fait de lier une pull request ouverte à un ticket ouvert qui n’a pas de statut, ou dont le statut est Backlog ou Todo, fait passer le ticket à En cours.
  `sender` est la personne ou l’application qui a lié la pull request. S’ils ne peuvent pas choisir un état pour le problème, l’état ne change pas.

GitHub n’envoie pas `status_changed` dans les cas suivants :

* L’état ne change pas, par exemple lorsque quelqu’un choisit l’état que le ticket a déjà.
* L’issue est transférée vers un autre référentiel. Le nouveau problème conserve son état, que la `transferred` charge utile inclut dans `changes.new_issue.status`.

### Modifications d’état qui ferment ou rouvrent un problème

Les statuts des catégories `duplicate`, `completed` et `not_planned` concernent les problèmes fermés. Le choix de l’un de ces états pour un problème ouvert ferme le problème et le choix d’un état dans n’importe quelle autre catégorie pour un problème fermé le rouvrir.

Lorsqu’un changement d’état ferme ou rouvert un problème, GitHub envoie deux livraisons : `status_changed`, et `closed` ou `reopened`. Les deux livraisons peuvent arriver dans n’importe quel ordre.

Le fait de passer un problème fermé à un état avec une autre raison de fermeture, par exemple de Terminé à Non planifié, envoie `status_changed` avec `changes.state_reason` mais sans `changes.state`.
GitHub envoie également une autre `closed` livraison avec le nouveau `state_reason`.

Si votre intégration gère `status_changed` ainsi que `closed` ou `reopened`, assurez-vous qu’elle peut gérer la même modification signalée par les deux livraisons.

## Livraison

GitHub fournit `status_changed` de la même façon que les autres événements de webhook. La livraison est effectuée au mieux.
GitHub ne garantit pas que chaque modification est remise exactement une fois, ou que les livraisons arrivent dans l’ordre dans lequel les modifications se sont produites.

* **Remises ayant échoué** : une remise peut échouer, par exemple si votre serveur n’est pas disponible.
  GitHub ne renvoie pas automatiquement les livraisons ayant échoué, mais vous pouvez les renvoyer. Pour plus d’informations, consultez « [Gestion des échecs de livraison des "webhooks"](/fr/webhooks/using-webhooks/handling-failed-webhook-deliveries) ».
* **Livraisons répétées** : vous pouvez recevoir la même livraison plusieurs fois, par exemple lorsqu’elle est renvoyée. Une redelivery a le même `X-GitHub-Delivery` en-tête que la remise d'origine. Vous pouvez donc utiliser l'en-tête pour ignorer les remises que vous avez déjà traitées.
* **Commande** : les livraisons peuvent arriver dans le désordre, et les payloads retardés, renvoyés ou réexpédiés peuvent être obsolètes, y compris `issue.status`. N’utilisez pas l’ordre dans lequel les livraisons arrivent pour déterminer l’état le plus récent d’un problème.

Pour obtenir le dernier état d’un problème, récupérez le problème avec l’API REST. Pour plus d’informations, consultez « [Points de terminaison d’API REST pour les problèmes](/fr/rest/issues/issues#get-an-issue) ». Dans les référentiels appartenant à une organisation, la réponse inclut `status` pour toute demande authentifiée, y compris les demandes authentifiées en tant qu’installation GitHub App et les demandes qui utilisent `GITHUB_TOKEN` dans un flux de travail. Pendant le aperçu, dans les référentiels appartenant à un compte personnel, la réponse inclut `status` uniquement lorsque la demande est effectuée pour le compte d’un utilisateur qui a accès à la préversion. Si la réponse n’inclut `status`pas , utilisez l’état des livraisons avec soin, car une livraison qui arrive ultérieurement peut porter un statut plus ancien.

## Qui peut modifier un statut

Les personnes disposant d’un accès de triage ou supérieur à un dépôt peuvent choisir l’état de ses tickets. Des règles d’autorisation supplémentaires s’appliquent aux rôles personnalisés, aux applications, aux flux de travail et aux comptes personnels :

* **Rôles de référentiel personnalisés** : dans les référentiels appartenant à une organisation, les personnes disposant d’un rôle personnalisé qui hérite du rôle Triage, Écriture ou Maintenance peuvent choisir des états. Les personnes disposant d’un rôle personnalisé qui hérite du rôle Lecture ne peuvent pas choisir des statuts, même si le rôle peut définir des types de tickets.
* **Applications et flux de travail** : dans les dépôts appartenant à une organisation, GitHub Apps disposant d’un accès en écriture pour l’autorisation de dépôt « Issues » peuvent également choisir des statuts, y compris les flux de travail qui utilisent `GITHUB_TOKEN` avec l’autorisation `issues: write` .
* **Comptes personnels** : Pendant la aperçu, dans les dépôts appartenant à un compte personnel, seules les personnes ayant accès à la préversion peuvent choisir des états.

Le choix d’un état qui ferme ou rouvre un problème nécessite également l’autorisation de fermer ou de rouvrir le problème. La modification de la raison pour laquelle un problème fermé est fermé, par exemple de Terminé à Non planifié, nécessite l’autorisation de fermer et de rouvrir le problème.

Les personnes qui ne peuvent pas choisir un statut peuvent toujours le modifier en fermant ou en rouvrant un problème. Par exemple, l’auteur d’une issue peut la fermer et la rouvrir avec un accès en lecture au référentiel, ce qui définit le statut par défaut du nouvel état. Ces modifications envoient également `status_changed`, et `sender` est la personne qui a fermé ou rouvert le problème.

## Exécution d’un flux de travail lorsqu’un état change

Pour exécuter un GitHub Actions flux de travail lorsque l’état d’un problème change, utilisez le `status_changed` type d’activité de l’événement `issues` . Le flux de travail s’exécute chaque fois que l’état d’un problème change. Dans le flux de travail, les propriétés suivantes du `github.event` contexte décrivent la modification.

* `github.event.status` contient l’état vers lequel le ticket a été modifié.
* `github.event.changes.status.from` contient l’état précédent ou `null` si le problème n’en avait pas.
* `github.event.issue.status` contient l’état du problème lorsque la charge utile a été générée. Les charges utiles pour chaque `issues` type d’activité incluent cette propriété.

> [!IMPORTANT]
> Les flux de travail qui utilisent l’événement `types` sans `issues` s’exécutent également pour `status_changed`. Ces flux de travail s’exécutent chaque fois que quelqu’un modifie l’état d’un problème et s’exécutent une fois supplémentaire lorsqu’un problème est créé, fermé ou rouvert, car GitHub envoie `status_changed` ainsi que `opened`, `closed` ou `reopened`. Pour éviter les exécutions inattendues, répertoriez les types d’activités dont votre flux de travail a besoin.

Lors de la aperçu, les éditeurs qui valident les fichiers de flux de travail, tels que l’éditeur de flux de travail sur GitHub, peuvent signaler `status_changed` en tant que type d’activité non valide. Vous pouvez ignorer cette erreur.

Par exemple, les flux de travail qui correspondent à un état par son ID et chaque état d’une catégorie, consultez [Événements qui déclenchent des flux de travail](/fr/actions/reference/workflows-and-actions/events-that-trigger-workflows#issues).

## Exemples de charges utiles

Les extraits suivants montrent les propriétés des `status_changed` payloads qui décrivent la modification. Les charges utiles complètes incluent également les objets complets `sender`, `repository` et `issue`, ainsi que d’autres propriétés.

### Création d’un problème

Lorsque quelqu’un crée un ticket sans choisir de statut, le ticket obtient le statut Backlog.
`changes.status.from` est `null`, et `changes` n’inclut ni `state` ni `state_reason`.

```json
{
  "action": "status_changed",
  "issue": {
    "number": 1347,
    "state": "open",
    "state_reason": null,
    "status": {
      "id": 2,
      "name": "Backlog",
      "category": "backlog"
    }
  },
  "status": {
    "id": 2,
    "name": "Backlog",
    "category": "backlog"
  },
  "changes": {
    "status": {
      "from": null
    }
  }
}
```

### Modification d’un état dans la même catégorie

Le déplacement d’un ticket de In progress vers In review ne change pas son état ni sa catégorie, donc seul `changes` inclut `status`.

```json
{
  "action": "status_changed",
  "issue": {
    "number": 1347,
    "state": "open",
    "state_reason": null,
    "status": {
      "id": 8,
      "name": "In review",
      "category": "started"
    }
  },
  "status": {
    "id": 8,
    "name": "In review",
    "category": "started"
  },
  "changes": {
    "status": {
      "from": {
        "id": 4,
        "name": "In progress",
        "category": "started"
      }
    }
  }
}
```

### Fermeture d’un problème en modifiant son statut

Le déplacement d’un ticket de In review vers Done ferme le ticket.
`changes.state.from` est `open`, et `changes.state_reason.from` est `null` parce que le problème n’a pas eu de raison d’état avant.
GitHub envoie également une `closed` livraison pour cette modification.

```json
{
  "action": "status_changed",
  "issue": {
    "number": 1347,
    "state": "closed",
    "state_reason": "completed",
    "status": {
      "id": 5,
      "name": "Done",
      "category": "completed"
    }
  },
  "status": {
    "id": 5,
    "name": "Done",
    "category": "completed"
  },
  "changes": {
    "status": {
      "from": {
        "id": 8,
        "name": "In review",
        "category": "started"
      }
    },
    "state": {
      "from": "open"
    },
    "state_reason": {
      "from": null
    }
  }
}
```