Hinweis
Problemstatus sind in Vorschau und nur für Konten verfügbar, die in der Vorschau registriert sind. Webhook-Nutzlasten und der status_changed Aktivitätstyp können geändert werden.
Informationen zu Statusänderungsereignissen
Wenn sich der Status eines Problems ändert, GitHub sendet ein issues Webhook-Ereignis mit der status_changed Aktion. Nutzlasten für jede issues Aktion enthalten auch den aktuellen Status des Problems in issue.status. Sie können diese Ereignisse verwenden, um andere Tools mit Ihren Issues zu synchronisieren oder einen GitHub ActionsWorkflow auszuführen, wenn ein Issue einen bestimmten Status erreicht.
Status werden nur für Issues in Repositorys aufgenommen, die Issue-Status verwenden. Für andere Issues enthalten Nutzdaten issue.status nicht, und GitHub sendet status_changed nicht.
Das vollständige Nutzlastschema finden Sie unter Webhook-Ereignisse und Webhook-Nutzlasten.
Statusobjekte
Webhook-Nutzlasten beschreiben jeden Status mit einem Objekt mit drei Eigenschaften.
| Property | Typ | Description |
|---|---|---|
id | Integer | Der Bezeichner des Status. |
name | String | Der Anzeigename des Status, z. B. In progress. Der Name kann sich ändern. |
category | String | Die Kategorie des Status, z. B. backlog, planned, started, completed, not_planned oder duplicate. Weitere Kategorien können in Zukunft hinzugefügt werden. |
Mehrere Status können derselben Kategorie angehören. Beispielsweise gehören „In Bearbeitung“ und „In Überprüfung“ beide zur started Kategorie. Um einen Status im Code oder Workflow abzugleichen, verwenden Sie dessen id. Um jeden Status in einer Kategorie abzugleichen, verwenden Sie dessen category. Keine Übereinstimmung anhand von name.
issue.status ist null, wenn das Issue keinen Status hat. Beispielsweise hat ein Problem, das erstellt wurde, bevor Status in seinem Repository verfügbar waren, keinen Status, bis jemand einen festlegt, oder bis das Problem geschlossen oder erneut geöffnet wurde.
Die status_changed Payload
Neben issueden , repositoryund senderden anderen Eigenschaften, die jede issues Nutzlast enthält, enthält eine status_changed Nutzlast die folgenden Eigenschaften. Bei dieser Aktion ist sender die Person oder App, die den Status geändert hat.
| Property | Description |
|---|---|
status | Der Status, zu dem das Problem geändert wurde. |
changes.status.from | Der Status, den das Problem vor der Änderung hatte, oder null wenn es keins hatte. |
changes.state.from | Der vorherige state des Issues, open oder closed. Nur enthalten, wenn die Statusänderung das Problem ebenfalls geschlossen oder erneut geöffnet hat. |
changes.state_reason.from | Das vorherige state_reason des Issues. Nur enthalten, wenn die Statusänderung auch den Zustandsgrund geändert hat, z. B. durch Schließen oder Erneutes Öffnen des Problems oder ändern, warum es geschlossen ist. Es ist null, wenn das Problem keinen Zustandsgrund hatte, z. B. wenn es zum ersten Mal geschlossen wird. |
Erfasste Werte und das aktuelle Issue
Die Eigenschaften status und changes beschreiben die Änderung zum Zeitpunkt des Speicherns. Die issue Eigenschaft, einschließlich issue.status, beschreibt den Vorgang, als die Lieferung erstellt wurde, identisch mit jeder anderen issues Aktion. Wenn sich der Vorgang vorher erneut ändert, kann issue.status von status abweichen. Wenn beispielsweise jemand ein Problem von „In Bearbeitung“ nach „In Überprüfung“ verschiebt und dann schnell zu „Fertig“ wechselt, kann die Übermittlung für die erste Änderung ein issue.status von „Fertig“ haben.
Um herauszufinden, was eine bestimmte Änderung getan hat, verwenden Sie status und changes. Eine verzögerte, wiederholte oder erneut zugestellte Nutzlast kann veraltet sein, daher ist issue.status möglicherweise nicht der letzte Status des Problems. Weitere Informationen finden Sie unter Zustellung weiter unten in diesem Artikel.
Wann status_changed gesendet wird
GitHub sendet status_changed jedes Mal, wenn sich der Status eines Problems ändert, einschließlich Änderungen, die GitHub vorgenommen werden, wenn ein Problem erstellt, geschlossen oder erneut geöffnet wird.
- Festlegen eines Status: Jemand wählt einen anderen Status für ein Problem aus.
- Erstellen eines Problems: Ein neues Problem erhält den Backlog-Status, es sei denn, die Person, die es erstellt, wählt einen anderen Status aus.
changes.status.fromistnull. GitHub sendetopenedsowiestatus_changed. - Festlegen eines ersten Status: Ein vorhandenes Issue ohne Status erhält einen.
changes.status.fromistnull. - Schließen oder erneutes Öffnen eines Problems: Wenn ein Problem als abgeschlossen geschlossen wird, wird der Status „Fertig“ festgelegt, das Schließen als nicht geplant setzt den Status „Nicht geplant“, und das Schließen als Duplikat setzt den Status „Duplikat“. Das erneute Öffnen eines Problems, ohne einen Status zu wählen, setzt den Status auf „Backlog“.
GitHub sendet
closedoderreopenedsowiestatus_changed. - Verknüpfen einer Pullanforderung: Das Verknüpfen einer offenen Pullanforderung mit einem offenen Issue, das keinen Status hat oder den Status „Backlog“ oder „Todo“ hat, verschiebt das Issue auf „In Bearbeitung“.
senderist die Person oder App, die den Pull Request verknüpft hat. Wenn sie keinen Status für das Problem auswählen können, ändert sich der Status nicht.
GitHub sendet in diesen Fällen nicht status_changed :
- Der Status ändert sich nicht, z. B. wenn jemand den Status auswählt, den das Problem bereits hat.
- Das Issue wird in ein anderes Repository übertragen. Das neue Problem behält seinen Status bei, den die
changes.new_issue.statusNutzlast intransferredenthält.
Statusänderungen, die einen Vorgang schließen oder erneut öffnen
Statuswerte in den Kategorien completed, not_planned und duplicate sind für geschlossene Vorgänge. Wenn Sie einen dieser Status für ein geöffnetes Problem auswählen, wird das Problem geschlossen, und wenn Sie einen Status in einer anderen Kategorie für ein geschlossenes Problem auswählen, wird es erneut geöffnet.
Wenn eine Statusänderung ein Problem schließt oder erneut öffnet, GitHub werden zwei Lieferungen gesendet: status_changedund closed oder reopened. Die beiden Lieferungen können in beliebiger Reihenfolge ankommen.
Das Ändern eines geschlossenen Issue in einen Status mit einem anderen Abschlussgrund, z. B. von „Fertig“ zu „Nicht geplant“, sendet status_changed mit changes.state_reason, aber ohne changes.state.
GitHub sendet auch eine weitere closed Lieferung mit dem neuen state_reason.
Wenn Ihre Integration sowohl verarbeitet status_changed als auch closed oder reopened, stellen Sie sicher, dass sie die gleiche Änderung verarbeiten kann, die von beiden Lieferungen gemeldet wird.
Lieferung
GitHub liefert status_changed auf die gleiche Weise wie andere Webhook-Ereignisse. Die Zustellung erfolgt nach bestem Bemühen.
GitHub garantiert nicht, dass jede Änderung genau einmal geliefert wird oder dass Lieferungen in der Reihenfolge eingehen, in der die Änderungen vorgenommen wurden.
- Fehlgeschlagene Lieferungen: Eine Zustellung kann fehlschlagen, z. B. wenn Ihr Server nicht verfügbar ist. GitHub liefert fehlgeschlagene Auslieferungen nicht automatisch erneut aus, aber Sie können sie erneut zurückverarbeiten. Weitere Informationen findest du unter Bearbeitung fehlgeschlagener Webhook-Zustellungen.
- Wiederholte Lieferungen: Sie können dieselbe Lieferung mehrmals erhalten, z. B. wenn sie erneut geliefert wird. Eine Wiederzustellung hat denselben
X-GitHub-DeliveryHeader wie die ursprüngliche Lieferung, sodass Sie den Header verwenden können, um Lieferungen zu überspringen, die Sie bereits verarbeitet haben. - Bestellung: Lieferungen können in beliebiger Reihenfolge eintreffen, und verzögerte, wiederholte oder erneut zugestellte Nutzlasten können veraltet sein, einschließlich
issue.status. Verwenden Sie nicht die Reihenfolge, in der Lieferungen ankommen, um den aktuellen Status eines Issue zu ermitteln.
Rufen Sie das Problem mit der REST-API ab, um den neuesten Status des Problems zu erhalten. Weitere Informationen findest du unter REST-API-Endpunkte für Issues. In Repositories, die einer Organisation gehören, enthält die Antwort status für jede authentifizierte Anfrage, einschließlich Anfragen, die als GitHub App-Installation authentifiziert sind, und Anfragen, die GITHUB_TOKEN in einem Workflow verwenden. Während des Vorschau umfasst die Antwort in Repositories persönlicher Konten status nur dann, wenn die Anforderung im Namen eines Benutzers erfolgt, der Zugriff auf die Vorschau hat. Wenn die Antwort status nicht enthält, verwenden Sie den Status von Lieferungen mit Sorgfalt, da eine Lieferung, die später eintrifft, einen älteren Status tragen kann.
Wer kann einen Status ändern?
Personen mit Triagezugriff oder höher für ein Repository können den Status seiner Issues auswählen. Zusätzliche Berechtigungsregeln gelten für benutzerdefinierte Rollen, Apps, Workflows und persönliche Konten:
- Benutzerdefinierte Repositoryrollen: In Repositorys, die einer Organisation gehören, können Personen mit einer benutzerdefinierten Rolle, die die Rolle "Triage", "Schreiben" oder "Verwalten" erbt, Status auswählen. Personen mit einer benutzerdefinierten Rolle, die die Read-Rolle erbt, können keine Status auswählen, auch wenn die Rolle Problemtypen festlegen kann.
- Apps und Workflows: In Repositorys, die einer Organisation gehören, können GitHub Apps mit Schreibzugriff für die Repository-Berechtigung „Issues“ ebenfalls Status auswählen, einschließlich Workflows, die
issues: writemit der BerechtigungGITHUB_TOKENverwenden. - Persönliche Konten: In VorschauRepositorys, die sich im Besitz eines persönlichen Kontos befinden, können nur Personen, die Zugriff auf die Vorschau haben, Status auswählen.
Wenn Sie einen Status auswählen, der ein Issue schließt oder erneut öffnet, ist auch die Berechtigung zum Schließen oder erneuten Öffnen des Issue erforderlich. Das Ändern des Grundes, warum ein geschlossenes Problem geschlossen ist, z. B. von „Fertig“ in „Nicht geplant“, erfordert die Berechtigung zum Schließen und erneuten Öffnen.
Personen, die keinen Status auswählen können, können ihn weiterhin ändern, indem sie ein Problem schließen oder erneut öffnen. Beispielsweise kann der Autor eines Problems es mit Lesezugriff auf das Repository schließen und erneut öffnen, wodurch der Standardstatus für den neuen Zustand festgelegt wird. Diese Änderungen senden auch status_changed, und sender ist die Person, die das Problem geschlossen oder erneut geöffnet hat.
Ausführen eines Workflows, wenn sich ein Status ändert
Um einen GitHub Actions Workflow auszuführen, wenn sich der Status eines Problems ändert, verwenden Sie den status_changed Aktivitätstyp des issues Ereignisses. Der Workflow wird immer ausgeführt, wenn sich der Status eines Problems ändert. Im Workflow beschreiben die folgenden Eigenschaften des github.event Kontexts die Änderung.
github.event.statusenthält den Status, in den das Problem geändert wurde.github.event.changes.status.fromenthält den vorherigen Status odernull, wenn das Problem keinen hatte.github.event.issue.statusenthält den Status des Problems, wenn die Nutzlast erstellt wurde. Nutzlasten für jedenissuesAktivitätstyp enthalten diese Eigenschaft.
Wichtig
Workflows, die das issues Ereignis ohne types verwenden, werden auch für status_changed ausgeführt. Diese Workflows werden immer ausgeführt, wenn jemand den Status eines Problems ändert, und zusätzlich einmal, wenn ein Problem erstellt, geschlossen oder erneut geöffnet wird, da closed sowohl reopened als auch opened, status_changed oder GitHub sendet. Um unerwartete Ausführung zu vermeiden, listen Sie die Aktivitätstypen auf, die Ihr Workflow benötigt.
Während des Vorschau können Editoren, die Workflowdateien überprüfen, z. B. der Workflow-Editor auf GitHub, status_changed als ungültigen Aktivitätstyp melden. Sie können diesen Fehler ignorieren.
Beispielworkflows, die anhand der Status-ID mit einem Status und mit allen Statuswerten in einer Kategorie abgeglichen werden, finden Sie unter Ereignisse zum Auslösen von Workflows.
Beispielnutzlasten
Die folgenden Auszüge zeigen die Eigenschaften von status_changed Nutzlasten, die die Änderung beschreiben. Vollständige Nutzlasten umfassen auch die vollständigen issue-, repository- und sender-Objekte sowie andere Eigenschaften.
Ein Problem erstellen
Wenn jemand ein Problem erstellt, ohne einen Status auszuwählen, erhält das Problem den Status "Backlog".
changes.status.from ist null, und changes enthält weder state noch 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
}
}
}
Wechseln zu einem Status in derselben Kategorie
Wenn Sie ein Problem von „In Bearbeitung“ in „In Überprüfung“ verschieben, ändert sich sein Zustand oder seine Kategorie nicht, sodass changes nur status enthält.
{
"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"
}
}
}
}
Ein Issue durch Ändern des Status schließen
Wenn Sie ein Problem von „In Überprüfung“ in „Erledigt“ verschieben, wird das Problem geschlossen.
changes.state.from ist open, und changes.state_reason.from ist null, weil das Problem zuvor keinen Statusgrund hatte.
GitHub sendet auch eine closed Zustellung für diese Änderung.
{
"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
}
}
}