Skip to main content
Skip to content

使用GitHub事件流

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

注意

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

关于 GitHub 事件流

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

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

事件通过 Server-Sent 事件(SSE)传递,因此客户端不需要 Webhook 执行的公共终结点。 这使得 Event Streams 非常适合在开发人员计算机上运行的代理和工具。

事件流仅在 GitHub.com 上可用。 它尚不可用 GHE.com 。

开始之前

  • 访问: 我们正在通过等候名单方式分批开放此功能。 若要加入等待列表,请填写 等待列表表单,当你的帐户获得访问权限时,我们会联系你。 我们为每个帐户启用事件流:

    • 对于用户令牌,我们将启用你的用户帐户。
    • 对于 GitHub App 安装令牌,我们会启用安装该应用的用户、组织或企业。 这包括其中安装的每个应用,包括位于 GitHub Actions 中的 GITHUB_TOKEN,但不包括成员自己的用户令牌。

    来自其他帐户的请求会返回 403 Forbidden 消息“未为此帐户启用事件订阅”。

  • 令牌: 使用用户令牌(personal access token、OAuth 令牌或 GitHub App 用户访问令牌)或 GitHub App 安装访问令牌。 不支持以自身身份进行身份验证的应用。

  • 权限: 用户或安装需要对订阅的拉取请求具有读取访问权限。

快速入门

这些示例对 API 调用使用 GitHub CLI(),对流使用 gh。

1.创建订阅

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

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:

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 替换为该值:

gh api -X DELETE /event-subscriptions/ID

API 参考

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

MethodRoute描述
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 的完整事件

处理流

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

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

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

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

  • 重复项和排序: 可能会多次收到同一事件,一个拉取请求的事件可以无序到达。 从 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采用退避策略重试。

已知的限制

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

提供反馈

我们很乐意听听什么是工作,什么不工作。 在GitHub 社区讨论区中分享反馈。