GitHub PR 事件流:设计可恢复的 CI 观察器

用当前提交对账避免误判,比较事件流、轮询与 Webhook,并用六组模拟输入验证故障边界。

值班工具正在等待一条 PR 的 CI。上午十点第一次构建通过,十点零一分开发者推了修复提交,十点零二分工具才连回网络,收到一条成功事件。页面上该不该显示「检查已通过」?如果工具记住的是最后一条消息,答案似乎是肯定的;如果它展示的是当前提交的状态,第一条要问的却是:这次成功属于哪个 SHA,另外几项检查有没有回来?

GitHub 在 2026 年 11 月 18 日宣布 GitHub CLI 2.105.0 支持用 Event Streams 等待 PR 变化。它让没有公网入口的脚本也能等到事件,但没有把事件变成关于整个 PR 的最终判断。这里设计的是一个供工程师查看的只读观察器:平时少做状态请求,断线后仍能追上现在的状态,并且只说出自己有证据支持的结论。它不执行合并,不改分支规则,也不替代 GitHub 对合并条件的判定。

一条成功消息究竟说了什么

依照 Event Streams 的交付约定,订阅针对一条 PR,通过 SSE 交付。连接以前和断线期间的事件不会补发,同一事件可能出现不止一次,接收顺序也可能与发生顺序不同。一个套件结束会给出套件结论,多个应用可以分别产生套件事件。提交状态接口写入的状态并不触发这一类套件事件。事件流没有一条「当前所有必需检查已经齐备」的总通知。

这份契约足够用来减少空转,却不足以用来重建审计流水。缺失的不是一个可靠的时间戳,而是可能根本没有来到客户端的一段历史。如果我们关心「现在需不需要继续盯着这条 PR」,状态对账能弥补这个缺口。如果需求变成「补出断线期间每一次短暂红灯的确切时刻」,事后读取不能把历史倒放。那就必须另行定义历史数据的来源与留存,不应把本篇设计改名成审计系统。

还有一个容易被忽略的层次:同一个 PR 会有不止一类提交。作者分支头、以基线试合并生成的提交、进入合并队列后的合并组,三者不是同一个检查对象。本文模型只观察作者分支头;明确承认没有权威证据覆盖另外两个对象,反而比一句笼统的「绿了」有用。GitHub 合并队列文档说明了队列如何为组合变更单独运行检查。

选型:先问你有多少条 PR 要看

最简单的方案是固定间隔读取。把当前头与状态读取放进同一个观察流程,不要求连接常驻,也不依赖预览资格。若只跟踪几个发布 PR,而且一分钟内发现变化已经够用,这是我会先交付的版本。缺点是空闲期仍有请求,最坏发现时间包含一个轮询间隔和请求本身的延迟;多个客户端整点一起醒还会制造尖峰。

第二种是事件加状态对账。事件只设置某条 PR 的待检查标记,观察器仍去读取现状。启动时、重新连接时和定时保底时,都从同一个入口发起观察。适合少量并行任务、经常从开发者机器运行、希望减少普通变更的感知延迟的场景。它不能让定时保底消失,也多出订阅寿命、断线退避和连接监控。根据当前官方资料,预览仅用于 GitHub.com、需要获准访问,订阅 24 小时到期,单个用户、应用或安装令牌的活动订阅上限是 100。不要把这个上限当作应用总体容量估算,更不要拿新建订阅来代替重用。

第三种适用于集中服务:让符合权限条件的 GitHub App 或 Webhook 把事件送到有公网入口的接收端,校验来源后放进持久队列,再由统一观察器读取。它适合跨多个仓库和需要集中运维的团队,但运维面扩大了:入口、密钥轮换、传输失败、队列堆积和多租户隔离都要负责。即使内部队列做了可靠投递,队列可靠也不表示上游所有变化都送到了。接收端签名验证、入队和状态判断应分开;如果服务没有公网入口或故障恢复没有专人接手,先实行第二种甚至第一种,比自建大型事件平台更划算。

数据流:一条 PR 只有一个在途观察

把观察键定义为仓库稳定标识加 PR 编号,显示的仓库名不拿来做全局唯一键。负责拆解事件的适配器、定时器和启动恢复程序都只能写该键的脏标记;它们不直接把展示状态写绿。工作器取得这个键后执行一次流程:读取 PR 状态和目标分支,读取该头提交及相应必要检查证据,再读 PR 确认对象没有变化,最终输出一条有观察时刻的快照。正常情况下,获取证据的阶段可能包含检查运行与提交状态两种 API 请求,页数另算。

在途时如果来了新事件,不要为每一条启动一个查询,而是增加一个本地代次,完成本轮后再补一轮。一个朴素实现是观察前记下代次,读完以后只有代次一致才清除脏标记。假设这时界面上一轮仍显示 B 通过,新事件来了,就将 B 快照标记为「待刷新」;这比等 B 上的慢请求结束再覆盖到 C 上安全。多实例时,可按 PR 键稳定分区,或用带有效期的租约和写入版本比较。单有租约不够,旧实例被暂停后仍可能回来写旧状态;比较观察代次,才不会让过期写回覆盖接班者的新结果。

分别记录最后事件时间、最近一次成功对账时间和最后一个已观察 SHA。事件时间很久以前,在安静仓库不能单独说明有故障;最后成功对账也变旧了,才应该把「正在获取」与「缓存过期」区分开来。不要把失败请求当作空检查列表,也不要向页面回填「通过」。读取失败时保留旧快照供人参考,并把状态显式改成陈旧或不可用。重新获得读取权限后再进行一次完整对账。

检查适配器:同名不等于同一项证据

规范化一条证据时,要保留 SHA、检查名称、来源及结论。内部必需检查键至少能分开检查运行和旧式提交状态;对来源有约束时还要识别预期应用。只按人类可见的名字分组,另一个同名检查一旦比真正的任务先结束,观察器便可能错误地报告通过。检查列表如有分页,必须读完本轮需要的范围,或者直接将证据标为不完整。不能只拿第一页的返回修补上次缓存:被删除、重跑或改名的记录可能留在旧快照里。

重跑的归并规则也属于适配器。若源接口能明确给出当前尝试,适配器按其语义选择;不知道哪条代表当前尝试时,输出未知,不按数组最后一条猜。如果某个组织认可特殊结论,应由其规范化策略决定如何映射。本文没有将所有平台的结论翻译成同一个成功白名单,避免本地布尔值冒充分支规则。

这套设计有意保留两个独立的输出:checks-observed 表示本观察器的配置项在指定 SHA 上均见到了合格证据;是否可合并由 GitHub 判断,还涉及审核、草稿、规则、队列及其他约束。即使前后两次读到同一个头,也无法获得跨 API 的事务性快照:头可能换走又换回,规则也可能刚改。因此快照要有时间,规则缓存要带版本,有这个局限仍然不能自动执行写动作。

只读判断的最小实现

下面的异步函数可直接放进现代 JavaScript 运行时。它的输入是两个模拟读取适配器:readPR 返回小写的 state、布尔值 draft、当前提交 head、目标分支 base 和观察到的基线 SHA target;readEvidence 返回规范化的证据数组,结论只允许 pass、fail、pending 或 unknown。读取失败应该抛错,由外层记录陈旧,不是返回空数据。例子中的键是内部命名,不是 GitHub 请求字段。

async function observe(io, required) {
  const a = await io.readPR();
  if (a.state !== "open" || a.draft) return { verdict: "inactive", sha: a.head };
  const rows = await io.readEvidence(a.head);
  const b = await io.readPR();
  if (a.head !== b.head || a.base !== b.base || a.target !== b.target ||
      a.state !== b.state || a.draft !== b.draft)
    return { verdict: "changed", sha: b.head };
  if (!required.length) return { verdict: "unknown", sha: b.head };
  const checks = required.map(key => {
    const matches = rows.filter(x => x.sha === a.head && x.key === key);
    return matches.length === 1 ? matches[0].result : "unknown";
  });
  const verdict = checks.every(x => x === "pass") ? "checks-observed"
    : checks.includes("fail") ? "failing"
    : checks.includes("unknown") ? "unknown" : "waiting";
  return { verdict, sha: b.head };
}

这个函数保守处理了六种输入。在模拟对象上实际执行的六项断言均通过:上一个头的成功不能补到当前头;当前头两项都通过时返回 checks-observed;读取中再推一笔时返回 changed;同一键的两个候选尝试无法消歧时返回 unknown;一项待定时返回 waiting;一项明确失败时可报告 failing。这些是纯内存测试,没有访问真实仓库,没有验证 GitHub 预览资格、API 分页、速率限制或 CLI 重连。要验证传输适配器,应另做集成测试:断开连接后更换头,再恢复连接,确认基准读取会发现新提交,即使期间没有补发事件。

如果只想在自己有权读取的测试仓库探索接口,可以先确认 gh --version,再把示例中的地址替换为测试 PR。下面的监听命令会创建或复用针对该 PR 的短期订阅,不修改 PR,也不要把它理解成零副作用的 GET。输出是提醒,不能直接交给上面的适配器当证据。

PR=https://github.com/OWNER/REPO/pull/NUMBER
gh event listen --resource "$PR" --timeout 20m --follow \
  --event com.github.pull_request.head.changed.v1,com.github.pull_request.check_suite.status.changed.v1,com.github.pull_request.state.changed.v1

按命令手册与文档,输出事件走标准输出,连接就绪提示走标准错误;看到连接就绪应主动读一次现状,监听超时退出码为 8。CLI 会尝试自动重连及重建过期订阅。外层不要假设已稳定获取每次内部断线和重连的结构化信号:如果只消费标准输出,周期对账和进程退出后的复读仍是必要的。需要精细管理连接周期时,再接入官方 SSE API 并用结构化结束信号驱动重连,保留随机退避;不要根据一行可变的人类文案编排全部恢复逻辑。退出监听并不会删除订阅;在共用凭据下不要清理来源不明的订阅。

容量估算与降级顺序

假设观察二十条活跃 PR,每轮平均三次证据和元数据读取,固定每三十秒轮询一次,则每分钟约一百二十次基础请求,分页和重试还没算进去。如果改为五分钟保底,并假设每分钟合并后另有六次按事件触发的观察,两者分别约十二次和十八次,共三十次。这里的三次只是简化平均量,不是前述代码的固定 HTTP 数;诸如基线 SHA 二次读取、分页、分开的状态端点都会拉高成本。在这个假设里节省来自减少空闲期读取,不来自 SSE 有某个固定的性能系数。遇到同一批 PR 同时更新,应按租户和仓库预算分摊,拉开保底读的起始时间,让并发超过上限时先排队而不是共同重试。

如果返回的是该账户未开放预览的错误,不要把它当暂时故障反复申请订阅:退到有上限的轮询,并显示当前走的是轮询。若读取 PR 本身也没有访问权,轮询不是绕过权限的方法,应把对应观察停止。服务端临时故障和限流则根据提示退避,恢复后先对账而非抢建一批订阅。PR 关闭、监控期满或没有读者时释放本地资源,只清理自己确认拥有且不再共享的订阅。线上值得追踪的不是累计收到了多少事件,而是活跃 PR 最长多久没拿到一份新证据、有没有观察持续排队以及多少结果因证据不足降为未知。

验收可以从一条实际使用的测试 PR 开始,分别制造正常成功、连接关闭期间变更、单个提交状态迟到三种场景。为正常路径记录当前 SHA 为何对应当前结论,而不只记录图标颜色;为断线场景验证保底读带来的最长发现时间;为迟到场景验证之前的状态为什么没有变绿。如果部署记录还要求解释每次状态变化,则另立事件留存目标,不要把验收改成回放这三种场景就宣称有历史保证。

我会先把读状态做准,再把事件接上。两条路径必须跑同一个判断,否则断线后会悄悄切换判断标准。最后,界面的一行描述就能暴露架构是否清楚:「在某一时刻,对某个提交,观察到配置中的检查通过。」它没有宣称此刻依旧有效,也没有宣称可以合并。这点克制让观察器在联网不稳、规则变动和预览不可用时仍然值得信任。

相关文章

评论

登录后即可参与讨论

暂无评论。