# Verwenden von GitHub Event Streams

GitHub Mit Ereignisstreams können Agents und Integrationen Änderungen an einer Ressource abonnieren, anstatt sie abzufragen.

> [!NOTE]
> 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](https://gh.io/event-streams-signup) 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](https://cli.github.com/) (`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](#using-github-cli-commands).

### 1. Erstellen eines Abonnements

Ersetzen Sie `OWNER`, `REPO` und `NUMBER` durch den Besitzer, den Repositorynamen und die Nummer der Pullanforderung.

```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)
```

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

```shell
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 `id`zu finden. Löschen Sie dann das Abonnement, und ersetzen `ID` Sie es durch diesen Wert:

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

```shell
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 N` beendet nach N Ereignissen und `--follow` hört weiter, bis Sie es beenden.
* `--timeout` beendet das Warten nach einer Dauer, z. B. `30m`, und wird mit Status `8` beendet.
* `--jq` und `--template` formatieren jedes Ereignis wie bei `gh api`. Zum Beispiel druckt `--jq .data.conclusion` nur 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` | `/event-subscriptions` | Erstellen Sie ein Abonnement. |
| `GET` | `/event-subscriptions` | Zeigen Sie Ihre aktiven Abonnements an, neueste zuerst. |
| `GET` | `/event-subscriptions/{subscription_id}` | Rufen Sie ein Abonnement ab. |
| `DELETE` | `/event-subscriptions/{subscription_id}` | Löscht ein Abonnement. |
| `GET` | `/event-subscriptions/{subscription_id}/events` | 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 Form `https://github.com/OWNER/REPO/pull/NUMBER` oder dessen REST-API-URL in der Form `https://api.github.com/repos/OWNER/REPO/pulls/NUMBER` ohne 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ück `422 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 `422` mit 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 Ereignisses
* `event`: der Ereignistyp
* `data`: das vollständige Ereignis als einzeiliges JSON [CloudEvent](https://cloudevents.io/)

## 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_url` ab, anstatt sich auf die Ereignisreihenfolge zu verlassen. Bei Review- und Check-Suite-Ereignissen kennzeichnet `api_url` das 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 einem `outcome` in `data`. Act on `outcome`, not on the optional `reason` field, because new `reason` values 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_TOKEN` kann 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](#handling-the-stream).

## Bereitstellen von Feedback

Wir würden gerne hören, was funktioniert und was nicht. Teilen Sie Feedback in der [GitHub Community-Diskussion](https://github.com/orgs/community/discussions/211595).