注意
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 上。
| Method | Route | 描述 |
|---|---|---|
POST | / | 创建订阅。 |
GET | / | 列出您的活动订阅,按最新顺序排列。 |
GET | / | 订阅 |
DELETE | / | 删除订阅。 |
GET | / | 通过 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:事件的 IDevent:事件类型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 社区讨论区中分享反馈。