# 使用GitHub事件流

GitHub 事件流允许代理和集成订阅对资源所做的更改，而不是轮询这些更改。

> [!NOTE]
> GitHub 事件流处于 公开预览 阶段，并且可能会发生变化。 在预览期间，我们可能会对 API、事件类型和限制进行重大更改，且可能仅提前很短时间通知。

## 关于 GitHub 事件流

GitHub 事件流允许代理和集成订阅对资源所做的更改，而不是轮询这些更改。 它当前支持拉取请求的事件。

为拉取请求创建一次订阅，使流保持打开状态，并且当你所订阅的内容发生变化时，GitHub 会向你发送事件。 然后，客户端可以从 REST API 提取最新状态。

事件通过 Server-Sent 事件（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`。

### 1.创建订阅

用拉取请求的所有者、存储库名称和编号替换 `OWNER`、`REPO` 和 `NUMBER`。

```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.删除订阅

完成后，关闭流。 删除订阅不会关闭其打开的流，因此请先关闭流。 使用 `id` 列出活动订阅，以查找订阅的 `gh api /event-subscriptions`。 然后删除该订阅，并将 `ID` 替换为该值：

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

## API 参考

所有路由都在 `https://api.github.com` 上。

| Method | Route | 描述 |
| --- | --- | --- |
| `POST` | `/event-subscriptions` | 创建订阅。 |
| `GET` | `/event-subscriptions` | 列出您的活动订阅，按最新顺序排列。 |
| `GET` | `/event-subscriptions/{subscription_id}` | 订阅 |
| `DELETE` | `/event-subscriptions/{subscription_id}` | 删除订阅。 |
| `GET` | `/event-subscriptions/{subscription_id}/events` | 通过 SSE 流式传输订阅的事件。 |

### 创建订阅

请求正文有两个字段：

* `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`: 一个或多个事件类型。 未知事件类型会返回 `422 Unprocessable Content`，错误消息中会列出这些类型名称。

订阅响应包括`id`、、、`event_types``created_at`、`expires_at`、和`url``events_url`。 `resource_url`

### 限制

* 订阅涵盖一个拉取请求。
* 订阅在创建后 24 小时过期。 若要继续接收事件，请创建新的订阅。
* 每个用户、应用和安装令牌最多可以有 100 个活动订阅。 继续创建会返回 `422`，并显示“超出订阅限制”消息。 删除不再需要的订阅。

## 事件类型

| 事件类型 | 发送时 | 
`api_url` 指向 |
| --- | --- | --- |
| `com.github.pull_request.check_suite.status.changed.v1` | 拉取请求头提交上的检查套件已完成，无论其结论如何。 | 检查套件 |
| `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` | 拉取请求合并、关闭、重新打开、标记为已准备好审阅或转换为草稿。 | 拉取请求 |

拉取请求通常有多个检查套件，每个应用一个检查套件，因此一次推送可以生成多个检查套件事件，而重新运行完成后会再生成一个检查套件事件。

每个审阅批注，以及每次回复审阅批注，也算作审阅。

事件当前只会告诉你有某些事情发生了变化，而不会告诉你具体更改了什么。 例如，审阅事件不包括评审的状态，而状态更改事件不表示拉取请求是合并还是关闭。 提取 `api_url` 以了解情况。

检查套件事件是例外：其 `data.conclusion` 字段始终存在，因此你可以在不提取的情况下判断传递失败。 它是 `failure`、`neutral`、`cancelled`、`action_required`、`timed_out`、`skipped`、`stale`、`startup_failure`、`unknown` 或 `success` 之一（此列表之外的结论）。

GitHub 仅在有人查看或请求拉取请求后检查合并冲突，因此合并冲突事件可能需要比其他事件更长的时间才能到达。

### 事件格式

流中的每个事件都有三个字段：

* `id`：事件的 ID
* `event`：事件类型
* `data`：作为单行 JSON [CloudEvent](https://cloudevents.io/) 的完整事件

## 处理流

事件流是长期连接，因此客户端需要处理遗漏、重复或无序事件以及结束的流。 请遵循这些做法以避免丢失或处理不当事件。

* **错过的事件：** 流仅在保持打开状态时传送事件，且不支持重放。 您将不会收到以下情况下发生的事件：

  * 打开流之前
  * 在创建订阅后的短暂时间内
  * 离线时

  订阅后，先获取一次拉取请求，以补上之前遗漏的内容。

* **重复项和排序：** 可能会多次收到同一事件，一个拉取请求的事件可以无序到达。 从 `api_url` 中获取当前状态，而不是依赖于事件顺序。 对于 review 和 check suite 事件，`api_url` 标识该评审或 check suite，因此您可以用它来去重。
* **心跳：** 当流处于空闲状态时，服务器会在最后一个事件或注释后的 15 秒内发送一行以 `:` 开头的注释。 忽略这些行。
* **结束流：** 当服务器结束流时，其最后一个事件是 `github.stream.end`，其中 `data` 中包含 `outcome`。 对 `outcome`可选字段执行操作，而不是对可选 `reason` 字段执行操作，因为 `reason` 可能会添加新值。

  * `subscription_ended`：订阅已过期，或者你失去了对该拉取请求的访问权限。 如果需要，请停止并创建新订阅。
  * `reconnect`：重新打开同一订阅上的流。 采用带抖动的退避策略；如果令牌可能已过期，请先刷新令牌。

* **意外断开连接：** 如果流在没有 `github.stream.end` 事件的情况下结束，请重新连接。
* **安装令牌：** 安装令牌会在一小时后过期，使用该令牌打开的流会在其过期后的下一次访问检查时结束。 在重新连接之前创建一个新的令牌。 A `GITHUB_TOKEN` 无法续期，因此请在作业完成前删除它创建的订阅。

## Errors

错误响应包括 `message`、`documentation_url` 和 `status`。

| Status | 怎么办 |
| --- | --- |
| `400` | 请求正文不是 JSON 对象。 修复请求。 |
| `401` | 令牌无效或已过期。 刷新并重试一次。 |
| `403` | 未为此帐户启用事件流，或者您是以应用而非用户或安装身份进行身份验证。 请勿重试。 |
| `404` | 订阅不存在、已过期或属于其他用户，或者你无法访问该拉取请求。 请勿重试。 |
| `422` | 
`resource_url`或`event_types`无效，或者您已达到订阅数量限制。 修复请求，或删除不再需要的订阅。 |
| `503` | 临时。 在 `Retry-After` 标头中指定的秒数后重试。 |
| `500`、`504` | 采用退避策略重试。 |

## 已知的限制

* **没有“所有检查均已完成”事件：** 你会为每个检查套件收到一个事件。 若要了解是否完成所有检查，请在每个事件后提取拉取请求的检查套件。
* **拉取请求对话注释：** 拉取请求的对话选项卡上的注释尚未生成事件。 审阅评论会产生事件，即审阅事件。
* **删除后仍打开的流：** 删除订阅尚不会关闭其仍处于打开状态的流。 在删除订阅之前，请自行关闭流。
* **无重播：** 请参阅 [处理流](#handling-the-stream)。

## 提供反馈

我们很乐意听听什么是工作，什么不工作。 在[GitHub 社区讨论区](https://github.com/orgs/community/discussions/211595)中分享反馈。