Skip to main content
Skip to content

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.

Remarque

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.

Objets de statut

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

PropriétéCatégorieDescription
idIntegerIdentificateur du statut.
nameStringNom d’affichage de l’état, tel que In progress. Le nom peut changer.
categoryStringCaté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.fromL’é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, 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" ».
  • 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 ». 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 statuspas , 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.

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.

{
  "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.

{
  "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.

{
  "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
    }
  }
}