# GitHub イベント ストリームの使用

GitHub Event Streams を使用すると、エージェントとインテグレーションは、リソースをポーリングする代わりに、リソースの変更の通知を購読できます。

> [!NOTE]
> GitHub イベント ストリームは パブリック プレビュー プレビューであり、変更される可能性があります。 プレビュー期間中は、API、イベントの種類、制限に対して、短い予告期間で互換性を損なう変更を加える場合があります。

## GitHub イベント ストリームについて

GitHub Event Streams を使用すると、エージェントと統合は、リソースをポーリングする代わりに、リソースの変更通知を購読できます。 現在、プルリクエストのイベントがサポートされています。

プル要求のサブスクリプションを 1 回作成し、そのストリームを開いたままにしておくと、サブスクライブした内容が変更されたときに GitHub がイベントを送信します。 その後、クライアントは REST API から最新の状態をフェッチできます。

イベントは Server-Sent Events (SSE) を介して配信されるため、クライアントは Webhook のように公開エンドポイントを必要としません。 これにより、Event Streams は、開発者のコンピューターで実行されているエージェントやツールに適しています。

イベント ストリームは、 GitHub.comでのみ使用できます。 
GHE.comではまだ使用できません。

## 始める前に

* **アクセス:** この機能は現在、待機リスト方式で提供しています。 待機リストに参加するには、[待機リスト フォーム](https://gh.io/event-streams-signup)に入力してください。アカウントにアクセス権が付与されたら、ご連絡します。 アカウントごとにイベント ストリームを有効にします。

  * ユーザー トークンの場合、お客様のユーザー アカウントが有効になります。
  * GitHub Appインストール トークンの場合、アプリがインストールされているユーザー、組織、または企業を有効にします。 これは、GitHub Actionsの`GITHUB_TOKEN`を含め、そこにインストールされているすべてのアプリを対象としますが、メンバー自身のユーザー トークンは含まれません。

  他のアカウントからの要求は、"イベント サブスクリプションはこのアカウントで有効になっていません" というメッセージで `403 Forbidden` を返します。

* **トークン:** ユーザー トークン ( personal access token、OAuth トークン、または GitHub App ユーザー アクセス トークン) または GitHub App インストール アクセス トークンを使用します。 アプリ自体としての認証はサポートされていません。

* **アクセス許可:** ユーザーまたはインストールには、サブスクライブするプル要求への読み取りアクセス権が必要です。

## クイック スタート

これらの例では、API 呼び出しに [GitHub CLI](https://cli.github.com/) (`gh`) を使用し、ストリームには `curl` を使用します。

### 1. サブスクリプションを作成する

`OWNER`、`REPO`、および`NUMBER`を pull request の所有者、リポジトリ名、および番号に置き換えます。

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

応答には、サブスクリプションの `id`、 `expires_at`、および `events_url`が含まれます。 
`--jq .events_url` オプションは、次の手順で必要な`events_url`のみを出力します。 新しいサブスクリプションが `201 Created`を返します。 同じプル リクエストとイベントの種類を持つサブスクリプションが既にある場合は、`200 OK`でそのサブスクリプションが返されます。

### 2. イベント ストリームを開く

`events_url`でストリームを開きます。 
`gh api` は、何かを印刷する前に応答全体を待機するため、 `curl -N`などのストリーミング クライアントを使用します。

```shell
curl -sS -N -H 'Accept: text/event-stream' \
  -H @<(printf 'Authorization: Bearer %s' "$(gh auth token --hostname github.com)") \
  "$EVENTS_URL"
```

表示するアクティビティをトリガーする前に、ストリームを開きます。 ストリームは、開いている間にのみ発生するイベントを配信します。

### 3. 最新の状態を取得する

各イベントは、変更が発生したことを示し、`api_url`識別子を提供します。 トークンで `api_url` をフェッチして、レビューまたはプル要求の現在の状態を読み取ります。

### 4. サブスクリプションを削除する

完了したら、ストリームを閉じてください。 サブスクリプションを削除しても開いているストリームは閉じられないため、まず自分でストリームを閉じてください。 
`gh api /event-subscriptions`を使用してアクティブなサブスクリプションを一覧表示し、サブスクリプションの`id`を見つけます。 次に、その値で `ID` を置き換えて、サブスクリプションを削除します。

```shell
gh api -X DELETE /event-subscriptions/ID
```

## API リファレンス

すべてのルートが `https://api.github.com`上にあります。

| Method | Route | Description |
| --- | --- | --- |
| `POST` | `/event-subscriptions` | サブスクリプションを作成します。 |
| `GET` | `/event-subscriptions` | アクティブなサブスクリプションを新しい順に一覧表示します。 |
| `GET` | `/event-subscriptions/{subscription_id}` | サブスクリプションに登録する。 |
| `DELETE` | `/event-subscriptions/{subscription_id}` | サブスクリプションを削除します。 |
| `GET` | `/event-subscriptions/{subscription_id}/events` | サブスクリプションのイベントを SSE 経由でストリーミングします。 |

### サブスクリプションの作成

要求本文には、次の 2 つのフィールドがあります。

* `resource_url`: プル リクエストの Web URL（`https://github.com/OWNER/REPO/pull/NUMBER`形式）、または REST API URL（`https://api.github.com/repos/OWNER/REPO/pulls/NUMBER`形式）で、追加のパス、クエリ、またはフラグメントを含まないもの。 どちらの形式も同じサブスクリプションを指し、応答は常に Web URL を返します。 レビューなど、プル リクエストの一部の URL は受け入れられません。
* `event_types`: 1 つ以上のイベント タイプ。 不明なイベントの種類は `422 Unprocessable Content`を返し、エラー メッセージにそれらの名前が示されます。

サブスクリプションの応答には、 `id`、 `resource_url`、 `event_types`、 `created_at`、 `expires_at`、 `url`、 `events_url`が含まれます。

### Limits

* サブスクリプションには、1 つのプルリクエストが含まれます。
* サブスクリプションは、作成されてから 24 時間後に有効期限が切れます。 イベントを受信し続けるために、新しいサブスクリプションを作成します。
* 各ユーザー、アプリ、およびインストール トークンは、最大 100 個のアクティブなサブスクリプションを持つことができます。 さらに作成すると、"サブスクリプションの制限を超えました" というメッセージとともに `422` が返されます。 不要になったサブスクリプションを削除してください。

## イベントの種類

| イベントの種類 | 送信時 | 
`api_url` はを指します |
| --- | --- | --- |
| `com.github.pull_request.check_suite.status.changed.v1` | pull request のヘッド コミットのチェック スイートは、その結論が何であれ完了します。 | チェックスイート |
| `com.github.pull_request.head.changed.v1` | プッシュの後など、プルリクエストのヘッド コミットが変更されます。 | プルリクエスト |
| `com.github.pull_request.merge_conflict.v1` | 
GitHub は、プル リクエストにマージの競合があることを検出します。 | プルリクエスト |
| `com.github.pull_request.review.submitted.v1` | 誰かが承認、変更要求、またはコメントのレビューを送信します。 | レビュー |
| `com.github.pull_request.state.changed.v1` | pull request はマージされ、クローズされ、再度開かれ、レビューの準備完了としてマークされるか、下書きに変換されます。 | プルリクエスト |

プル要求には通常、アプリごとに 1 つずつ、複数のチェック スイートがあるため、1 つのプッシュで複数のチェック スイート イベントが生成され、再実行によって完了時に別のチェック スイートが生成されます。

1 回のレビュー コメント、およびレビュー コメントに対する各返信もレビューとしてカウントされます。

イベントは現在、何が変わったのかではなく、何かが変わったことを示しています。 たとえば、レビュー イベントにはレビューの状態が含まれず、状態変更イベントでは、プル要求がマージされたか閉じられたかは示されません。 
`api_url`を取得して調べる。

スイート イベントのチェックは例外です。 `data.conclusion` フィールドは常に存在するため、フェッチせずに失敗を見分けることができます。 これは、 `success`、 `failure`、 `neutral`、 `cancelled`、 `timed_out`、 `action_required`、 `stale`、 `skipped`、 `startup_failure`、または `unknown` のいずれかです (このリスト外の結論)。

GitHub は、誰かがプルリクエストを表示または作成した後にのみマージ競合をチェックするため、マージ競合イベントの到着には他のイベントよりも時間がかかる場合があります。

### イベントの形式

ストリーム内の各イベントには、次の 3 つのフィールドがあります。

* `id`: イベントの ID
* `event`: イベントタイプ
* `data`: 1 行の JSON [CloudEvent](https://cloudevents.io/) としてのイベント全体

## ストリームの処理

イベント ストリームは有効期間の長い接続であるため、クライアントは、ギャップ、繰り返しまたは順序外のイベント、および終了したストリームに対処する必要があります。 イベントを見逃したり、誤って処理したりしないようにするには、次のプラクティスに従います。

* **見落とされたイベント:** ストリームは、リプレイ機能はなく、開いている間にのみイベントを配信します。 次のようなイベントは受け取りません：

  * ストリームを開く前に
  * サブスクリプションを作成した直後の短い期間
  * オフライン時

  サブスクライブした後、プル要求を 1 回フェッチして、見逃した内容をキャッチします。

* **重複と順序付け:** 同じイベントを複数回受信する可能性があり、1 つのプル要求のイベントが順不同で到着する可能性があります。 イベントの順序に依存するのではなく、 `api_url` から現在の状態をフェッチします。 レビューおよびチェック スイートイベントの場合、 `api_url` はレビューまたはチェックスイートを識別するため、それを使用して重複除去できます。
* **ハートビート:** ストリームがアイドル状態の間、サーバーは最後のイベントまたはコメントから 15 秒以内に `:` で始まるコメント行を送信します。 これらの行は無視します。
* **ストリームの終了:** サーバーがストリームを終了すると、最後のイベントは`github.stream.end`で、`outcome`に`data`が含まれます。 オプションの`reason`フィールドではなく、`reason`に基づいて処理してください。新しい`outcome`値が追加される可能性があるためです。

  * `subscription_ended`: サブスクリプションの有効期限が切れたか、pull request にアクセスできなくなりました。 停止し、必要に応じて新しいサブスクリプションを作成してください。
  * `reconnect`: 同じサブスクリプションのストリームをもう一度開きます。 ジッターを加えて待機し、トークンの有効期限が切れている可能性がある場合は、最初にトークンを更新します。

* **予期しない切断:** ストリームが `github.stream.end` イベントなしで終了した場合は、再接続します。
* **インストール トークン:** インストール トークンは 1 時間後に期限切れになり、有効期限が切れた後の次回のアクセス チェック時にストリームの一方の端が終了します。 再接続する前に、新しいトークンを作成してください。 
`GITHUB_TOKEN` トークンは更新できないため、ジョブが完了する前にそれが作成したサブスクリプションを削除してください。

## Errors

エラー応答には、 `message`、 `documentation_url`、および `status`が含まれます。

| Status | 何をすべきか |
| --- | --- |
| `400` | リクエストボディは JSON オブジェクトではありません。 リクエストを修正してください。 |
| `401` | トークンが無効であるか、有効期限が切れています。 更新してから、もう一度お試しください。 |
| `403` | このアカウントに対してイベント ストリームが有効になっていないか、ユーザーまたはインストールではなくアプリとして認証されています。 再試行しないでください。 |
| `404` | サブスクリプションが存在しないか、有効期限が切れているか、別のユーザーに属しているか、プル要求にアクセスできません。 再試行しないでください。 |
| `422` | 
`resource_url`または`event_types`が無効であるか、サブスクリプションの制限に達しています。 要求を修正するか、不要になったサブスクリプションを削除してください。 |
| `503` | 一時的。 
`Retry-After` ヘッダー内の秒数の値の後に再試行してください。 |
| `500`、`504` | バックオフを使用して再試行します。 |

## 既知の制限

* **「すべてのチェックが完了しました」イベントはありません。** チェック スイートごとに 1 件のイベントがあります。 すべてのチェックが完了したかどうかを確認するには、各イベントの後に pull request のチェック スイートをフェッチします。
* **Pull request の会話コメント:** pull request の [会話] タブのコメントでは、まだイベントが生成されません。 レビュー コメントも、レビュー イベントと同様にイベントを生成します。
* **削除後も開いたままのストリーム:** サブスクリプションを削除しても、開いているストリームはまだ閉じられません。 サブスクリプションを削除する前に、ストリームを自分で閉じます。
* **再処理なし:** [ストリームの処理](#handling-the-stream)を参照してください。

## フィードバックの提供

何が機能していて、何が機能していないのかを聞いてみたいと思います。 
[GitHub コミュニティのディスカッション](https://github.com/orgs/community/discussions/211595)でフィードバックを共有します。