Hinweis
GitHub Ereignisdatenströme befinden sich in der Vorschau Öffentliche Vorschau und können sich ändern. Während der Vorschau können wir kurzfristig nicht abwärtskompatible Änderungen an der API, Ereignistypen und Beschränkungen vornehmen.
Informationen zu GitHub Event Streams
GitHub Mit Ereignisstreams können Agents und Integrationen Änderungen an einer Ressource abonnieren, anstatt sie abzufragen. Es unterstützt derzeit Ereignisse für Pull Requests.
Sie erstellen einmal ein Abonnement für einen Pull Request, halten einen Stream offen, und GitHub sendet Ihnen ein Ereignis, wenn sich etwas ändert, das Sie abonniert haben. Ihr Client kann dann den neuesten Status aus der REST-API abrufen.
Ereignisse werden über Server-Sent Events (SSE) übermittelt, sodass Ihr Client keinen öffentlichen Endpunkt benötigt, wie es bei Webhooks der Fall ist. Dadurch eignet sich Event Streams gut für Agents und Tools, die auf dem Computer eines Entwicklers ausgeführt werden.
Event Streams ist nur auf GitHub.com verfügbar. Es ist auf GHE.com noch nicht verfügbar.
Bevor du anfängst
-
Zugriff: Wir führen diese Funktion über eine Warteliste ein. Um der Warteliste beizutreten, füllen Sie das Wartelistenformular aus, und wir werden Sie kontaktieren, wenn Ihrem Konto Zugriff gewährt wurde. Wir aktivieren Ereignisdatenströme pro Konto:
- Für Benutzertoken aktivieren wir Ihr Benutzerkonto.
- Bei GitHub App Installationstoken aktivieren wir den Benutzer, die Organisation oder das Unternehmen, für den/die/das die App installiert ist. Dies deckt jede dort installierte App ab, einschließlich der GitHub Actions in
GITHUB_TOKEN, aber nicht die eigenen Benutzertoken der Mitglieder.
Anfragen von anderen Konten werden mit der Meldung „Ereignisabonnements sind für dieses Konto nicht aktiviert“ zurückgegeben
403 Forbidden. -
Token: Verwenden Sie ein Benutzertoken (a personal access token, ein OAuth-Token oder ein GitHub App Benutzerzugriffstoken) oder ein GitHub App Installationszugriffstoken. Apps, die als sich selbst authentifizieren, werden nicht unterstützt.
-
Berechtigungen: Der Benutzer oder die Installation benötigt Lesezugriff auf den Pull Request, den Sie abonnieren.
Quickstart
Diese Beispiele verwenden die GitHub CLI (gh) für die API-Aufrufe und curl den Datenstrom, sodass Sie jeden Schritt der API sehen können. Wenn Sie 2.105.0 oder höher verwenden GitHub CLI , behandeln die gh event Befehle das Abonnieren, Streaming und erneute Verbinden für Sie. Siehe Verwenden von GitHub CLI Befehlen.
1. Erstellen eines Abonnements
Ersetzen Sie OWNER, REPO und NUMBER durch den Besitzer, den Repositorynamen und die Nummer der Pullanforderung.
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)
Die Antwort umfasst das id, expires_at und events_url des Abonnements. Mit der Option --jq .events_url wird nur events_url gedruckt, die Sie im nächsten Schritt benötigen. Ein neues Abonnement gibt 201 Created zurück. Wenn Sie bereits über ein Abonnement mit denselben Pullanforderungs- und Ereignistypen verfügen, erhalten Sie dieses Abonnement wieder mit 200 OK.
2. Öffnen Sie den Ereignisdatenstrom
Öffnen Sie den Datenstrom unter events_url.
gh api wartet vor dem Drucken auf die gesamte Antwort. Verwenden Sie daher einen Streamingclient wie curl -N:
curl -sS -N -H 'Accept: text/event-stream' \
-H @<(printf 'Authorization: Bearer %s' "$(gh auth token --hostname github.com)") \
"$EVENTS_URL"
Öffnen Sie den Datenstrom, bevor Sie die Aktivität auslösen, die Sie anzeigen möchten. Der Datenstrom liefert nur Ereignisse, die auftreten, solange er geöffnet ist.
3. Den neuesten Zustand abrufen
Jedes Ereignis gibt an, dass eine Änderung aufgetreten ist, und stellt eine api_url bereit. Rufen Sie api_url mit Ihrem Token ab, um den aktuellen Status des Review oder Pull Requests zu lesen.
4. Löschen des Abonnements
Wenn Sie fertig sind, schließen Sie den Datenstrom. Durch das Löschen eines Abonnements werden die geöffneten Datenströme nicht geschlossen. Schließen Sie den Datenstrom also zuerst selbst. Auflisten Sie Ihre aktiven Abonnements, um gh api /event-subscriptions die Abonnements idzu finden. Löschen Sie dann das Abonnement, und ersetzen ID Sie es durch diesen Wert:
gh api -X DELETE /event-subscriptions/ID
Verwenden von GitHub CLI Befehlen
GitHub CLI 2.105.0 und höher enthalten gh event Befehle für Ereignisdatenströme. Diese Befehle sind ebenfalls in Öffentliche Vorschau enthalten und können sich ändern.
Um auf ein Ereignis für eine Pullanforderung zu warten, führen Sie gh event listen mit der URL der Pullanforderung und einem oder mehreren Ereignistypen aus:
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 erstellt ein Abonnement oder verwendet Ihr vorhandenes Abonnement für dieselben Pull-Request- und Ereignistypen. Anschließend öffnet er den Datenstrom und druckt jedes Ereignis als eine Zeile JSON. Es wird erneut verbunden, wenn der Datenstrom abbricht, und das Abonnement wird erneut erstellt, wenn das Abonnement abläuft.
- Standardmäßig wird der Befehl nach dem ersten Ereignis beendet. Dies passt zu Agents, die in der Regel warten, bis ein Befehl abgeschlossen ist, bevor sie fortfahren.
--count Nbeendet nach N Ereignissen und--followhört weiter, bis Sie es beenden.--timeoutbeendet das Warten nach einer Dauer, z. B.30m, und wird mit Status8beendet.--jqund--templateformatieren jedes Ereignis wie beigh api. Zum Beispiel druckt--jq .data.conclusionnur die Schlussfolgerung einer Check-Suite.
Der Befehl gibt Listening for events. nach dem Öffnen des Datenstroms auf stderr aus. Änderungen, die zuvor vorgenommen wurden, werden nicht gemeldet. Lesen Sie daher den aktuellen Zustand des Pull Requests, nachdem diese Zeile angezeigt wurde.
Um Abonnements direkt zu verwalten, verwenden Sie gh event subscription list, create, view und delete.
gh event listen löscht das Abonnement beim Beenden nicht. Abonnements laufen nach 24 Stunden ab.
Wenn gh erkennt, dass ein Agent es aufruft, schlagen Befehle wie gh pr create, gh pr view, gh run view, gh run watch und gh api gh event listen anstelle von Abfragen vor.
Führen Sie für alle Optionen aus gh event listen --help.
API-Referenz
Alle Routen sind auf https://api.github.com.
| Methode | Route | Beschreibung |
|---|---|---|
POST | / | Erstellen Sie ein Abonnement. |
GET | / | Zeigen Sie Ihre aktiven Abonnements an, neueste zuerst. |
GET | / | Rufen Sie ein Abonnement ab. |
DELETE | / | Löscht ein Abonnement. |
GET | / | Streamen Sie die Ereignisse des Abonnements über SSE. |
Erstellen eines Abonnements
Der Request-Body weist zwei Felder auf:
resource_url: die Web-URL des Pull Requests in der Formhttps://github.com/OWNER/REPO/pull/NUMBERoder dessen REST-API-URL in der Formhttps://api.github.com/repos/OWNER/REPO/pulls/NUMBERohne zusätzlichen Pfad, Abfrage oder Fragment. Beide URL-Formen bezeichnen dasselbe Abonnement, und die Antwort gibt immer die Web-URL zurück. URLs für einen Teil einer Pullanforderung, z. B. eine Überprüfung, werden nicht akzeptiert.event_types: ein oder mehrere der Ereignistypen. Unbekannte Ereignistypen geben zurück422 Unprocessable Content, und die Fehlermeldung benennt sie.
Abonnementantworten umfassen id, resource_url, event_types, created_at, expires_at, url und events_url.
Grenzen
- Ein Abonnement deckt einen Pull Request ab.
- Abonnements laufen 24 Stunden nach der Erstellung ab. Um Ereignisse weiterhin zu empfangen, erstellen Sie ein neues Abonnement.
- Jedes Benutzer-, App- und Installationstoken kann bis zu 100 aktive Abonnements haben. Wenn weitere erstellt werden, wird
422mit der Meldung "Abonnementgrenzwert überschritten" zurückgegeben. Löschen Sie Abonnements, die Sie nicht mehr benötigen.
Ereignistypen
| Ereignistyp | Gesendet, wenn |
api_url verweist auf |
| --- | --- | --- |
| com.github.pull_request.check_suite.status.changed.v1 | Eine Check-Suite auf dem Head-Commit des Pull Requests wird beendet, was auch immer ihr Ergebnis ist. | Die Check-Suite |
| com.github.pull_request.head.changed.v1 | Der Head-Commit des Pull Requests ändert sich, z. B. nach einem Push. | Der Pull Request |
| com.github.pull_request.merge_conflict.v1 |
GitHub findet, dass der Pull Request einen Zusammenführungskonflikt aufweist. | Der Pull Request |
| com.github.pull_request.review.submitted.v1 | Jemand sendet ein Review, das genehmigt, Änderungen anfordert oder kommentiert. | Die Review |
| com.github.pull_request.state.changed.v1 | Der Pull Request wird zusammengeführt, geschlossen, erneut geöffnet, als bereit für die Überprüfung markiert oder in einen Entwurf konvertiert. | Der Pull Request |
Eine Pullanforderung verfügt in der Regel über mehrere Check-Suites, eine pro App, sodass ein Push mehrere Check Suite-Ereignisse erzeugen kann und eine erneute Ausführung eine weitere erzeugt, wenn sie abgeschlossen ist.
Jeder einzelne Review-Kommentar und jede Antwort auf einen Review-Kommentar zählt ebenfalls als Review.
Ereignisse sagen Ihnen derzeit, dass etwas geändert wurde, nicht das, was sich geändert hat. Beispielsweise enthält ein Überprüfungsereignis nicht den Status der Überprüfung, und ein Zustandsänderungsereignis gibt nicht an, ob die Pullanforderung zusammengeführt oder geschlossen wurde. Rufen Sie api_url ab, um das herauszufinden.
Check suite events are the exception: their data.conclusion field is always present, so you can tell pass from fail without fetching. Es ist eines von success, failure, neutral, cancelled, timed_out, action_required, stale, skipped, startup_failure oder unknown (eine Schlussfolgerung außerhalb dieser Liste).
GitHub sucht nur nach Merge-Konflikten, nachdem jemand den Pull Request ansieht oder anfordert, sodass Merge-Konflikt-Ereignisse länger dauern können als andere Ereignisse.
Ereignisformat
Jedes Ereignis im Datenstrom weist drei Felder auf:
id: die ID des Ereignissesevent: der Ereignistypdata: das vollständige Ereignis als einzeiliges JSON CloudEvent
Umgang mit dem Datenstrom
Ereignisdatenströme sind langlebige Verbindungen, sodass Ihr Client Lücken, wiederholte oder out-of-order-Ereignisse und endende Ereignisströme verarbeiten muss. Befolgen Sie diese Methoden, um fehlende oder fehlerhafte Ereignisse zu vermeiden.
-
Verpasste Ereignisse: Datenströme liefern Ereignisse nur, wenn sie geöffnet sind, ohne Wiederholung. Sie erhalten keine Ereignisse, die auftreten:
- Vor dem Öffnen des Datenstroms
- Während eines kurzen Fensters unmittelbar nach dem Erstellen des Abonnements
- Während Sie getrennt sind
Rufen Sie nach dem Abonnieren den Pull Request einmal ab, um alles zu erfassen, was Sie verpasst haben.
-
Duplikate und Sortierung: Sie können dasselbe Ereignis mehrmals empfangen, und Ereignisse für eine Pullanforderung können außerhalb der Reihenfolge eingehen. Rufen Sie den aktuellen Zustand von
api_urlab, anstatt sich auf die Ereignisreihenfolge zu verlassen. Bei Review- und Check-Suite-Ereignissen kennzeichnetapi_urldas Review oder die Check-Suite, sodass Sie es zur Deduplizierung verwenden können. -
Heartbeats: Während sich der Datenstrom im Leerlauf befindet, sendet der Server innerhalb von 15 Sekunden nach dem letzten Ereignis oder Kommentar eine Kommentarzeile, die mit
:beginnt. Ignorieren Sie diese Zeilen. -
Beenden eines Datenstroms: Wenn der Server einen Datenstrom beendet, ist das letzte Ereignis
github.stream.end, mit einemoutcomeindata. Act onoutcome, not on the optionalreasonfield, because newreasonvalues may be added.subscription_ended: Das Abonnement ist abgelaufen, oder Sie haben den Zugriff auf den Pull Request verloren. Beenden Sie den Vorgang, und erstellen Sie bei Bedarf ein neues Abonnement.reconnect: Öffnen Sie den Datenstrom im selben Abonnement erneut. Verzögern Sie Wiederholungsversuche mit Jitter und aktualisieren Sie Ihr Token zuerst, wenn es möglicherweise abgelaufen ist.
-
Unerwartete Trennungen: Wenn ein Stream ohne ein
github.stream.end-Ereignis endet, verbinden Sie sich erneut. -
Installationstoken: Installationstoken laufen nach einer Stunde ab, und geöffnete Datenströme werden bei der nächsten Zugriffsprüfung beendet, nachdem das Token abgelaufen ist. Erstellen Sie ein neues Token, bevor Sie die Verbindung erneut herstellen. Eine
GITHUB_TOKENkann nicht verlängert werden, löschen Sie deshalb vor Abschluss des Auftrags die von ihr erstellten Abonnements.
Errors
Fehlerantworten umfassen message, documentation_url und status.
| Status | Was zu tun ist |
|---|---|
400 | Der Anforderungstextkörper ist kein JSON-Objekt. Korrigieren Sie die Anfrage. |
401 | Ihr Token ist ungültig oder abgelaufen. Aktualisieren Sie es, und wiederholen Sie es einmal. |
403 | Event Streams ist für dieses Konto nicht aktiviert, oder Sie authentifizieren sich als App anstatt als Benutzer oder Installation. Versuchen Sie es nicht erneut. |
404 | Das Abonnement ist nicht vorhanden, ist abgelaufen oder gehört zu einem anderen Benutzer, oder Sie können nicht auf den Pull Request zugreifen. Versuchen Sie es nicht erneut. |
422 | Die resource_url oder event_types ist ungültig, oder Sie haben die Abonnementgrenze erreicht. Korrigieren Sie die Anfrage, oder löschen Sie Abonnements, die Sie nicht mehr benötigen. |
503 | Temporär. Wiederholen Sie den Vorgang nach der im Retry-After Header angegebenen Anzahl von Sekunden. |
500, 504 | Wiederholen Sie den Vorgang mit "Backoff". |
Bekannte Einschränkungen
- Es gibt kein Ereignis „Alle Prüfungen abgeschlossen“: Sie erhalten ein Ereignis pro Check-Suite. Um zu wissen, ob alle Prüfungen abgeschlossen sind, rufen Sie die Check-Suites der Pullanforderung nach jedem Ereignis ab.
- Konversationskommentare zu Pull Requests: Kommentare auf der Registerkarte „Konversation“ des Pull Requests erzeugen noch keine Ereignisse. Review-Kommentare hingegen schon, und zwar als Review-Ereignisse.
- Offene Streams nach dem Löschen: Das Löschen eines Abonnements schließt seine offenen Streams noch nicht. Schließen Sie den Stream selbst, bevor Sie das Abonnement löschen.
- Commit-Status: Check-Suite-Ereignisse decken keine Commit-Status ab, die mit der REST-API erstellt wurden. Wenn die erforderlichen Prüfungen einer Pullanforderung Commit-Status enthalten, rufen Sie sie separat ab.
- Keine Wiedergabe: Siehe Behandeln des Datenstroms.
Bereitstellen von Feedback
Wir würden gerne hören, was funktioniert und was nicht. Teilen Sie Feedback in der GitHub Community-Diskussion.