GitHub Event Streams 进入预览:告别反复轮询,仍要处理断线与状态校验

等待代码审查或 CI 结果时,自动化程序常常反复询问 GitHub:有新反馈吗,检查结束了吗?查得频繁,许多请求没有新信息;间隔拉长,又会延迟后续处理。

GitHub 于 2026 年 11 月 17 日发布 Event Streams 预览公告。页面标注的发布时间为 UTC 18:00,北京时间是 11 月 18 日 02:00,处于本次写作的过去 24 小时内。它允许客户端订阅拉取请求变化,通过长连接接收通知,不必先搭建公网 Webhook 接收服务。

这并不是一条保证完整历史的消息队列。官方指南明确说明,事件流没有重放,客户端还要应对重复、乱序和断线。比较稳妥的设计是让通知唤醒程序,再读取当前状态决定下一步。本文依据官方资料分析,没有申请预览资格、创建订阅或在本项目中接入 Event Streams。

背景:本机工具也需要及时知道远端变化

对运行在开发者电脑上的代理或命令行工具,轮询容易接入,但需要自己决定查询间隔。Webhook 则通常需要可被 GitHub 访问的接收端,长期运行的服务可以承担这项工作,临时启动的本机任务未必值得为此维护一个入口。

Event Streams 使用 Server-Sent Events(SSE)。客户端主动建立连接并保持打开,GitHub 在发生已订阅变化时发送事件。因此,它省去了公网接收端,比较适合“跟踪一个正在处理的拉取请求”这类会话式任务。

目前它仍是公共预览,需要通过候补名单获批。公告说各 GitHub 套餐均可申请,不代表所有账号已经能直接调用。指南还限定当前仅支持 GitHub.com,尚不支持 GHE.com;预览期间 API、事件类型和限制可能发生破坏性变化。

核心机制:通知与业务状态分两步读取

接入流程是先为一个拉取请求创建订阅,取得 events_url,再用支持流式输出的客户端连接它。官方示例特别指出,gh api 会等完整响应后才输出,不适合直接观察这个持续打开的事件流;示例改用 curl -N。

当前事件覆盖提交头变化、审查提交、合并冲突、拉取请求状态变化,以及检查套件完成等情况。多数事件只告诉客户端发生了变化,并提供 api_url,不会直接给出完整业务结论。例如,状态事件本身不说明究竟是合并还是关闭,审查事件也不直接包含审查结论。

检查套件事件是一个例外,其 data.conclusion 会带上该套件的结果。但这仍是一个套件的结果,不是整个拉取请求的最终结果。

这里可以把客户端分成两层。连接层负责接收、重连和续期;业务层读取当前状态,判断是否需要回复审查、继续修改或结束等待。两层分开后,网络重连不会直接变成重复的业务操作。

没有重放,就不能把连接当作历史账本

官方文档列出了几个可能错过事件的窗口:流打开之前、订阅刚创建后的短暂间隔,以及客户端断线期间。SSE 消息中存在 id 字段,也不能据此推断服务支持按 ID 补齐历史。

指南建议订阅后读取一次拉取请求,弥补遗漏。对长期运行的客户端,重连后再做一次状态核对,也是基于这一限制给出的工程建议。需要验证的是“现在是否还有工作”,不能只依赖“我刚才有没有收到通知”。

重复与乱序也需要单独处理。若先收到较新的状态通知,再收到较旧的通知,按到达顺序直接覆盖本地结论可能使状态倒退。读取 api_url 获取当前状态,有助于避免这种误判。审查和检查套件事件的 URL 还可帮助识别对应对象并去重。

但识别出同一对象,不等于所有副作用天然幂等。如果客户端会发评论、重试作业或修改文件,还应记录已经处理的对象与状态。把同一份事件再喂给模型一次,并不能代替程序层的重复处理保护。

“一个检查完成”不是“全部检查通过”

一个拉取请求可能关联多个检查套件。一次推送可产生多个套件事件,重新运行检查也会在完成时再次产生事件。当前没有统一的“所有检查完成”事件。

因此,收到某个套件的 success 后立即判定可以合并,会把单个结果误当成全局结论。官方要求在事件后查询拉取请求的检查套件,判断整体完成情况。若自动化还要执行合并,则仍应遵守仓库要求的检查、审查和权限规则;Event Streams 不替客户端做这些业务决策。

此外,拉取请求会话页上的普通评论暂不产生事件,审查评论则属于支持范围。合并冲突事件也可能有延迟,因为 GitHub 要在有人查看或请求该拉取请求后才检查冲突。不能把暂时没有事件理解为所有风险都已排除。

连接生命周期需要单独验收

空闲时,服务器会发送以 : 开头的注释心跳,客户端应忽略这些行,不把它们当成新任务。服务器主动结束流时,会发送 github.stream.end,程序应依据 data.outcome 分支处理,而不是依赖可能扩展的 reason 文本。

收到的结果或情况 客户端应如何处理
subscription_ended 停止当前流,确认订阅或访问权限,仍有需要时新建订阅
reconnect 对同一订阅重新连接,使用带抖动的退避,必要时先刷新令牌
未收到结束事件便断开 重新连接,并核对当前状态
订阅已删除 不能假定连接同时关闭,客户端还须自行关闭流

订阅在创建 24 小时后过期,需要继续接收时应创建新订阅。GitHub App 安装令牌则有更短的有效期,指南说明其一小时后过期,连接会在之后的访问检查时结束。因此,订阅续期与认证刷新是两件事。

本地代理也不宜把所有错误都放进无限重试循环。官方对未开通功能或认证主体不受支持的 403 明确要求不要重试;对临时服务错误才采用相应等待或退避策略。先辨认错误性质,才能避免把权限问题变成持续的无效请求。

实践启示:验收恢复能力,而不只演示一次通知

如果团队准备试用,可以在隔离的测试仓库中建立一组可重复的检查:连接前改变状态、主动断网后恢复、重复输入同一事件、调整事件顺序、让多个检查套件先后结束。每项测试都应核对最终读取的状态,以及是否出现重复业务操作。

这是建议的测试方案,并非本博客已经执行的实验,也不构成吞吐或延迟承诺。预览接入时还应记录 API 和事件类型的假设,避免把今天的限制隐藏在客户端代码里。

结语

Event Streams 给本机自动化增加了一种及时获知变化的方式,减少了反复查询“有没有新消息”的需求。它保留的边界也很清楚:通知可能遗漏、重复或乱序,检查完成事件的粒度也有限。

让事件流负责唤醒,让 API 提供当前状态,再由明确的业务规则决定动作,才能在连接断开或消息重复时仍然得出可靠结论。

参考来源

文章目录
  1. 1. 背景:本机工具也需要及时知道远端变化
  2. 2. 核心机制:通知与业务状态分两步读取
  3. 3. 没有重放,就不能把连接当作历史账本
  4. 4. “一个检查完成”不是“全部检查通过”
  5. 5. 连接生命周期需要单独验收
  6. 6. 实践启示:验收恢复能力,而不只演示一次通知
  7. 7. 结语
  8. 8. 参考来源
|