merge queue 已启用但零 workflow 声明 `merge_group` —— 队列里一个检查都不跑,进队列的 PR 只会空转并锁死自己的分支

[os-zhuang]

现象

#4422(发布 PR)被加入 merge queue 后一直没有合并,同时 main 上的 Release workflow(run 30821243525)失败:

[command]/usr/bin/git push origin HEAD:changeset-release/main --force
remote: error: GH006: Protected branch update failed for refs/heads/changeset-release/main.
remote: - A pull request for this branch has been added to a merge queue. Branches that
remote:   are queued for merging cannot be updated. To modify this branch, dequeue the
remote:   associated pull request.

根因

.github/workflows/ 下 17 个 workflow,没有一个声明 merge_group 触发器:

$ for f in .github/workflows/*.yml; do grep -q merge_group "$f" || echo "no  $(basename $f)"; done
no  check-links.yml
no  ci.yml
no  codeql.yml
no  coverage-nightly.yml
no  docker-publish.yml
no  docs-drift-check.yml
no  engine-split-metric.yml
no  lint.yml
no  pr-automation.yml
no  publish-smoke.yml
no  release.yml
no  rerun-safety-nightly.yml
no  scaffold-e2e.yml
no  showcase-smoke.yml
no  spec-liveness-check.yml
no  stale.yml
no  validate-deps.yml

GitHub 的 merge queue 是把 PR 推测性地合并到当前 main 生成一个 merge group,然后在这个 merge group 上重跑必需检查、只有全绿才落地 —— 这正是 AGENTS.md §7 说它「就是 §10 的重新验证,由平台做,无竞态」的原因。但检查要跑起来,workflow 必须声明 on: merge_group。一个都没有,于是队列里不会触发任何 CI:必需检查永远不满足,条目空转到队列超时被踢出。

两处代价

1. 对任何 PR:进队列等于什么也不会发生,还白等一轮超时。
2. 对发布 PR 尤其致命:队列会锁住 changeset-release/main,而 changesets/action 在每次 main push 时都要 force-push 刷新这个分支 —— 于是发布 PR 一旦进队列,就同时(a)自己拿不到新 CI,(b)让后续每一次 main push 的 Release job 以 GH006 整个失败。chore: version packages (rc) #4422 正是卡在这个死结上:它的 CI 结果停在旧 workflow 的那一次,而修好的 workflow 推不进来。

与文档的冲突

AGENTS.md「Multi-agent working discipline §7」写着:

Once the repo's merge queue is enabled, "add to queue" IS the sanctioned path —— it is the opposite of the auto-merge this rule bans: the queue builds your PR as merged onto the current main and lands it only if that speculative result is green

按现在的配置,这句话指向的是一个陷阱:队列已启用,但它 build 出来的 merge group 上没有任何检查会跑,「only if that speculative result is green」这个前提不成立。文档和实际配置必须对齐 —— 要么补触发器让队列真能干活,要么在文档里明确「队列尚不可用,走 §7 的手工串行兜底」。

可选方向(未决,需要维护者拍板)

• 补 merge_group 触发器:让队列名副其实。代价是每个 merge group 都要跑一遍全量 CI(本仓库的 Test Core / Dogfood / Temporal 等都不便宜),是仓库级的 CI 成本变更。可能需要同时收敛「必需检查」清单,只让真正必需的那几个跑在 merge group 上。
• 暂时关掉 merge queue,并把 AGENTS.md §7 改回手工串行,等成本方案定了再开。
• 无论选哪条,changeset-release/main 都值得单独考虑是否应该被排除在队列之外 —— 它是机器生成、随时被重写的分支,进队列的语义本身就可疑。

---

发现于修 #4894(#4896)之后跟进 #4422 的过程中。本 issue 只做记录,未认领。

[os-zhuang]

实证更正:队列不是「空转超时」,而是零检查直接合并

开 issue 时我按「必需检查永远不满足 → 条目空转到超时被踢出」推测了后果。实际发生的更严重,记录在案。

#4422 于 14:19:21 合并,merged_by 是人,但触发 main 上后续 Release run(30822140425)的 actor 是:

"actor":            {"login": "github-merge-queue[bot]"}
"triggering_actor": {"login": "github-merge-queue[bot]"}
"head_sha":         3cfd9f0b17d1cf71a934ed4ed1f9d7e9eb1e2c03

即队列确实把它合进了 main。而由于没有任何 workflow 声明 merge_group,这次合并没有跑过任何一个检查 —— merge group 上零 CI,队列直接判定「无阻塞」并落地。

合并时 #4422 携带的 CI 结果是 13:42 那一次的旧 run,其中两个 job 是红的(Check Changeset、Scaffold with repo dist,成因见 #4894)。这两个红灯恰好是 CI 闸门自身的缺陷、不是产品问题,所以这次合并的结果无害 —— 但那是运气,不是机制。

这把问题的性质改变了:

• 原判断:队列不可用(进去就卡住)。代价是浪费时间。
• 实际情况:队列可用但空转验证(进去就合)。代价是它成了绕过 §10 重新验证的最短路径。

AGENTS.md §7 的原文是:

the queue builds your PR as merged onto the current main and lands it only if that speculative result is green, which is exactly the §10 re-verification, done by the platform, race-free

按现在的配置,only if that speculative result is green 这个前提不成立 —— 没有检查跑,就没有 green 可言,条件恒真。文档把「加入队列」推荐成 sanctioned path,而它实际执行的是「不重新验证就合并」,正是 §7 开头明令禁止的 gh pr merge --auto 的效果。

所以修复的紧迫性比原文写的要高一档:在补上 merge_group 触发器(或关掉队列)之前,「加入队列」应当被视为禁止操作,AGENTS.md §7 需要同步修正。

---

Generated by Claude Code

[os-zhuang]

分诊:过时前提 —— 核心缺陷已在 main 上修复,关闭(completed)。

• 实测证据(origin/main @ 229d29e):merge_group 触发器已存在于 4 个 workflow —— ci.yml、lint.yml、spec-liveness-check.yml,另有专设的 merge-queue-triage.yml。「零 workflow 声明 merge_group」的立单前提不再成立。
• 行为佐证:队列近两日的运行记录(多次「CI 红被踢出队列 → 修后重投全绿」,见 flaky: spec/src/cloud/tenant.test.ts 的 #4739 导出面用例贴着 5s 超时 —— 今晚已两次把不相干的 PR 踢出合并队列 #4796 一族与 [PM] 分片分工登记表 — 谁在管哪个仓库的队列 #4604 各车道登记)证明 merge group 上确实在跑必需检查并按结果拦截 —— 「零检查直接合并」的追记情形已不可复现,AGENTS.md §7 描述的语义(speculative result green 才落地)与现配置一致。
• 残留疑点处置:changeset-release/main 是否应排除在队列语义之外(本单第三个可选方向)未见专项处理,但其触发场景(发布 PR 入队锁死分支)自 merge_group 生效后未再复现;若 GH006 再现,按当时症状重新立单,不留一个挂在已修前提上的旧单占扫描位。
• 维护者如认为残留面值得单独跟踪,可重开或另立窄单。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code