一条分支要穿过几道闸门才能回到主干 左边是 PR 合并框的缩影:两项检查通过、一项评审在等、一处冲突,下面是合并按钮。右边是一条从主干分出去的分支,沿途立着三道闸门,最后一道是强调色,穿过之后才汇回主干上的合并点。 ✓ test ✓ lab/outside-ci ● Review required ✗ conflicts Merge pull request mergeable_state: dirty

打开一个 GitHub 上的 PR,往下拉到合并按钮那一块,能看到的提示五花八门:Some checks were not successful、Review required、This branch is out-of-date with the base branch、This branch has conflicts that must be resolved、Merging is blocked,有的仓库还有 Merge when ready、This branch was successfully deployed。仓库设置里对应的开关更多:必需检查、必需评审、CODEOWNERS、与主干同步、合并队列、部署环境……

可同样是 GitHub,也有很多仓库这一块空空如也,合并按钮永远是绿的。我在一个没有配置任何规则的仓库里开了个测试 PR,故意让它的检查失败,然后点合并:照样合进去了。

那这些提示到底哪些真能拦住合并?一个项目该开哪几样,开了之后又要付出什么?我先拿四个测试 PR(下文叫 PR A、B、C、D)把几个关键现象实测了一遍,再顺着“合并前到底想保证什么”往下理。

一、合并按钮由什么决定

两条永远生效的卡点

先把合并按钮的逻辑拆开看。不需要任何配置就能拦住合并的,只有两样:

  • draft:draft PR 不能合并1,要先点 Ready for review;
  • 冲突:PR 和主干改了同一处,合并不出来,mergeable_state 是 dirty。

除此之外,合并框里的所有东西,检查的红叉、Request changes 的评审、“落后主干”的提示、部署状态,默认都只是展示。PR B 的检查失败后,mergeable_state 是 unstable,意思就是“有检查没通过,但它们都不是必需的”2,按钮照样能点。

规则把信号变成关卡

让这些信号拦住合并的,是分支规则:在仓库设置里给 main 配一条分支保护规则(branch protection rule)或 ruleset,在里面点名“哪个检查必须通过”“要几个人批准”“必须与主干同步”“哪个环境必须部署成功”3。被点名的信号不满足,合并框才会出现 Merging is blocked;没被点名的,只是摆在那里给人看。

规则决定哪些信号能拦住合并 左边是 PR 上的六个信号:检查 test 失败、评审 Request changes、落后主干 2 个提交、staging 部署成功、draft 为 false、没有冲突。中间是一条示例规则,只点名了必需检查 test,评审、同步、部署都没配置。于是只有 test 失败通过规则传到合并按钮,按钮显示 Merging is blocked;其他三个信号止步于规则,只做展示;draft 和冲突不经过规则,直接作用在按钮上。 PR 上出现的信号 分支规则 · main(示例) 合并按钮 检查 testfailure 评审Request changes 落后主干2 commits 部署 stagingsuccess 永远生效的两条 draftfalse 冲突无 点名了什么 required checktest approvals未配置 up to date关 deployments未配置 虚线:没被点名的信号 止步于此,只做展示 不经过规则 合并框 Merging is blocked 原因:test 必需且失败 draft 和冲突不需要规则, 直接作用在按钮上
图 1 · 合并按钮只看两样东西:永远生效的 draft 和冲突,以及被规则点名的信号

所以理清这些东西,关键不是记住每个开关,而是先回答一个问题:合并到主干之前,你想保证什么? 归纳下来只有四种保证,后面四节一节讲一种,每种都回答三件事:不开会出什么事、最少开哪几样、开了要付出什么。

  1. 这次改动本身没坏:检查,并把它设为必需;
  2. 合进去以后主干也没坏:与主干同步,或合并队列;
  3. 该看的人看过:必需评审和 CODEOWNERS;
  4. 上线是可控的:部署环境和它的审批。

二、保证一:改动本身没坏

不开会怎样

最常见的事故是“忘了跑一下”:改了一行配置,本地没构建就推上去合了,主干从此构建失败。给仓库加一个在 PR 上跑构建和测试的 workflow,就能在合并前看到结果。

最少开什么

一个 pull_request 触发的 workflow。 GitHub Actions 的每个 job 会在 PR 的 head 提交上留下一条检查(check run),外部 CI 一般用 commit status 上报,两者在合并框里显示在一起4。对一个人的项目,这一步往往就够了:自己看到红叉自然不会去点合并。

再把检查设为必需。 多人协作,或者不想依赖“看到红叉自觉不合”,就在分支规则里把这个检查的名字(比如 test)列为 required status check。下表是同一个检查状态在“没有规则”和“列为必需”时的区别,其中有三行是开了以后最容易踩的坑。

同一个检查状态,有没有规则结果不同
head 提交上 test 的状态没有规则规则要求 test 必须通过
success可合并(clean)可合并
failure红叉,但可合并(unstable,PR B 实测)不可合并(blocked)
还在跑可合并(unstable)不可合并,等结果
job 被 if 跳过(skipped)可合并算通过
workflow 被路径过滤,没运行可合并一直等待,永远合不了
只在旧提交上通过可合并不算数,要在新提交上重跑

“可合并”指检查这一项不拦;评审、冲突等其他条件另算。

图 2 · 检查本身只是报告,只有被规则点名的检查才会锁住合并按钮

被路径过滤掉的那一行最常见:workflow 写了 paths: ['src/**'],某个 PR 只改了文档,workflow 根本不运行,必需检查就一直显示 Waiting for status to be reported,这个 PR 永远合不了5。办法是让必需的那个 workflow 不加路径过滤,在 job 里面用 if 判断要不要真跑:被 if 跳过的 job 记为 skipped,按通过处理。

检查测的是“合并后的样子”

开了必需检查以后,还要知道它到底测的是什么。PR A 的 workflow 打印了自己的环境:

event=pull_request action=opened
GITHUB_SHA=bef7b38723f09a4ef78fb74d9845f29b0ece00a5
GITHUB_REF=refs/pull/N/merge
pr_head_sha=e796c534c1291c1193570d0a3a00f7ddfbb4d347

跑的不是 PR 的 head 提交 e796c53,而是 GitHub 在后台把它合进主干得到的测试合并提交 bef7b386。也就是说,检查测的是“如果现在合并,主干会变成什么样”,跑完再把结果挂回 head 提交。

这带来两个后果。一是 PR 里改 workflow 文件会立刻生效:PR D 把 workflow 里的版本号改成 v2-head,它的运行打印的就是 v2-head。二是有冲突时检查不会跑:PR C 和主干冲突后再推一个提交,一个 workflow 都没触发,因为测试合并提交生成不出来。所以看到“检查一直不动”,先看看是不是有冲突。

检查跑在测试合并提交上,冲突时它生成不出来 左边是 PR A:主干提交 236b111,PR 的 head 提交 e796c53,GitHub 把两者合成测试合并提交 bef7b38,放在 refs/pull/N/merge 上,workflow 在它上面跑,结果挂回 e796c53。右边是 PR C:主干前进到 bb3a2c9,与 head 提交 2035e4d 冲突,测试合并提交生成不出来,pull_request 事件不运行任何 workflow。 PR A · 能合并 PR C · 有冲突 236b111 主干 lab/pr-gates-base e796c53 refs/pull/N/head bef7b38 refs/pull/N/merge 虚线框:GitHub 算出来的测试合并 提交,workflow 在它上面跑 236b111 bb3a2c9 主干也新建了 lab-shared.txt d3705a7 2035e4d ✗ 合并不出来:没有测试合并提交, 推 2035e4d 后一个 workflow 都没跑 mergeable_state: dirty
图 3 · 检查测的是“合并后的样子”;合并不出来,检查就不会开始

检查测的是“合并后的样子”,可这个样子是拿当时的主干算的。主干往前走了,这个绿色还算数吗?

三、保证二:合进去以后主干也没坏

不开会怎样

这是实验里最能说明问题的一段:

  1. PR A 打开,检查在 bef7b38(PR A 合进旧主干 236b111)上通过。
  2. PR B 带着一个会让测试失败的 FAIL 文件合进了主干,主干变成 77f0799。
  3. PR A 转为 ready for review,又跑了一次,用的仍是旧的 bef7b38,依然通过。
  4. PR A 再推一个提交,新的测试合并提交 aeaa0d5 基于 77f0799,带上了 FAIL,检查失败。

PR A 自己什么都没做错。但在第 2 步到第 4 步之间,它挂着一个绿色的结果,而这个结果测的是一个已经不存在的主干。这时候点合并,主干就会坏掉。两个 PR 各自都是绿的,合在一起却是红的,这就是“保证一”管不到的地方。第 3 步还说明测试合并提交是后台异步重算的,事件到来时未必已经更新(这是根据日志推断的,文档没写重算时机)。

主干前进后,PR A 的绿色结果过期了 时间从左到右:01:24:31 PR A 打开,检查在 bef7b38 上通过;01:25:21 PR B 合入,主干变成 77f0799;01:25:31 PR A 转为 ready,检查仍在旧的 bef7b38 上通过;01:26:00 PR A 推新提交,测试合并提交变成 aeaa0d5,基于 77f0799,检查失败。 01:24:31 01:25:21 01:25:31 01:26:00 主干 PR A 的动作 测试结果 236b111 77f0799 PR B(带 FAIL)合入 opened · e796c53 ready_for_review push · 8be4454 bef7b38 ✓ 还是 bef7b38 ✓ aeaa0d5 ✗ 虚线框:基于已过时的主干
图 4 · 绿色结果只对算它时的主干有效,主干一动它就可能过期

最少开什么:与主干同步

在必需检查的规则里勾上 Require branches to be up to date before merging3。PR 只要落后主干,合并框就显示 This branch is out-of-date with the base branch,要先点 Update branch 把主干合进来,检查在新组合上重跑,通过了才能合。

代价是排队。 主干每合进一个 PR,其他所有打开的 PR 都会变成落后,都要更新、重跑、再等。一天几个 PR 时这点等待无所谓;PR 一多,大家就在抢“谁先跑完谁先合”,跑完又落后了。

PR 多了:换成合并队列

合并队列(merge queue)把“更新、重跑、合并”从作者手里接过去7。作者点 Merge when ready 把 PR 放进队列,GitHub 依次为每个 PR 生成临时分支,测“主干 + 前面所有排队的 PR + 这个 PR”,通过就合,失败就把这个 PR 踢出去,后面的重建。

合并队列为每个排队的 PR 测试“主干加前面所有 PR” 队列里有 #101、#102、#103 三个 PR。GitHub 生成三个临时分支:main 加 #101,main 加 #101 和 #102,main 加三个。第二组检查失败,#102 被移出队列,第三组去掉 #102 重建为 main 加 #101 和 #103 再测。 示意 · gh-readonly-queue/main/…(每行触发一次 merge_group) pr-101-… pr-102-… pr-103-… 重建 pr-103 main #101 ✓ 合入 main #101 #102 ✗ 移出 main #101 #102 #103 作废 main #101 #103 ✓ 合入 虚线:包含失败 PR 的组,结果作废
图 5 · 合并队列把“与主干同步再测”变成后台流水线,作者不用自己追着主干更新

它有两个前提。workflow 必须加上 merge_group 触发事件,否则队列里的临时分支等不到必需检查,最后超时出队;而且它只对组织所有的公开仓库,或 Enterprise Cloud 组织的私有仓库开放8。用不了合并队列的仓库,就停在“与主干同步”这一步,最多再打开 auto-merge,让 PR 在条件满足时自动合并9。它只替你点按钮,不替你更新分支。

机器能保证的到此为止。改动对不对、该不该这样改,还得靠人。

四、保证三:该看的人看过

不开会怎样

没有评审规则时,评审也只是展示:有人点了 Request changes,作者照样能合。几个人一起写代码时,这意味着“看没看过”全凭自觉。

最少开什么:必需评审

在分支规则里打开 Require a pull request before merging,设置需要几个批准3。一个批准就能挡住“没人看过就合了”。在它下面还有几个子开关,每个都堵一种“批准了,但没人看过最终代码”的情况:

评审相关的规则开关,各堵哪个漏洞
开关不开会怎样开了以后
Required approvals(N 个)没人看也能合至少 N 个有写权限的人批准
Dismiss stale approvals批准后再推新代码,旧批准仍然有效改动后旧批准作废,要重新批准
Require review from Code OwnersCODEOWNERS 只负责发评审请求改到谁的文件,必须有对应 owner 批准
Require approval of the most recent push作者推完最后一下自己就能凑齐最后一次推送必须由推送者以外的人批准
Require conversation resolution评审意见没处理也能合所有评审对话标记为已解决才能合

管理员默认可以绕过,除非同时勾上 Do not allow bypassing the above settings。

图 6 · 评审规则的每个子开关都对应一种“批准了但其实没人看过最终代码”的情况

最常一起开的是前两项:至少一人批准,有新推送就作废旧批准。后两项适合对安全要求更高的仓库。

有分区负责人:CODEOWNERS

当仓库大到“这个目录必须让某人看过”,就加一个 CODEOWNERS 文件,把路径对应到人或团队10。它本身只负责自动发评审请求;要让这个人的批准成为必需,还得在规则里打开 Require review from Code Owners。读取的是 base 分支上的 CODEOWNERS,PR 自己改它不影响这次的评审人;作者不会被请求评审自己的 PR。

draft 是给人看的信号

draft 也属于“人”这一类:它告诉评审者“还没写完,先别看”,所以 draft 不会请求 code owner 评审,转为 ready 时才发出请求1。但它不会让检查停下来,PR A 以 draft 打开时,workflow 一个 job 不少地跑了。想让 draft 不跑 CI,要在 job 上自己写 if: github.event.pull_request.draft == false。

前三种保证都在合并之前。合并之后要上线,又由谁来拦?

五、保证四:上线是可控的

合并和部署是两件事

PR B 合并时,同一秒触发了两次运行:主干收到合并提交 77f0799 的 push 事件,以及 PR 的 pull_request closed 事件,后者的 github.event.pull_request.merged 为 true6。部署一般挂在主干的 push 上,PR 相关的善后(通知、清理预览环境)挂在 closed 上。

如果什么都不配,合并就等于上线。想在中间加一道人工确认,靠的不是分支规则,而是部署环境(environment):在部署 job 上写 environment: production,再给这个环境配上必需审批人、等待时间或允许部署的分支11。这样合并照常发生,部署 job 停在等待状态,审批通过前不开始,也拿不到这个环境的 secret。

合并之后,部署由环境规则来拦 左边是实测:PR B 合并生成提交 77f0799,同时触发 push 和 pull_request closed(merged 为 true)两次运行。右边是示意:push 触发的部署 job 先部署 staging 环境,没有规则,立即运行;再部署 production 环境,配了必需审批人,job 停在等待状态,而这时 PR 早已合并。 合并(实测 · PR B) 部署(示意) 77f0799 合并提交 push on-push ✓ pull_request closed merged=true ✓ job deploy · environment: staging 无保护规则 → 立即运行 ✓ job deploy · environment: production required reviewers → Waiting 虚线框:job 已创建,在等审批;这时 PR 早已合并,合并按钮不受环境规则影响。 要让部署成为合并前提,得在分支规则里另开 Require deployments to succeed。
图 7 · 环境规则拦的是部署 job,不是合并按钮

反过来,如果希望“预发环境部署成功”是合并的前提,就在分支规则里打开 Require deployments to succeed before merging,点名 staging 环境3。前者拦部署,后者拦合并,别混在一起。

六、按场景选

选型

把四种保证和它们的代价放在一起,就能按项目的情况挑。一般是从上往下逐行加,到“够用”为止:

按场景逐行往下加
场景在上一行基础上加代价
一个人的小项目一个 pull_request 触发的 workflow,不设必需也行几乎没有
要求主干始终能构建把检查设为必需;必需的 workflow 不加路径过滤检查红了就合不了,得先修
几个人,一天几个 PR与主干同步;必需评审 1 人;新推送作废旧批准合并要等人,要排队更新分支
有分区负责人CODEOWNERS + Require review from Code Owners负责人不在时会卡住
PR 多到排不过来合并队列替换“与主干同步”;workflow 加 merge_group只对组织公开仓库或 Enterprise Cloud 开放
合并即上线production 环境加审批;需要时让 staging 部署成功成为合并前提上线多一步人工确认

draft 和冲突两条不用配,任何场景都生效。

图 8 · 从上往下逐行加,到够用为止

规则写在哪

这些开关可以写在分支保护规则里,也可以写在 ruleset 里12。一个分支同时只受一条分支保护规则管;ruleset 则可以多条叠加,同一项取最严格的值,还能单独停用、给某些角色设置绕过,有读权限的人都能看到。新配置建议直接用 ruleset。需要注意,在免费计划下,这两种规则都只能用于公开仓库,私有仓库要升级计划(个人 Pro 的私有仓库能否用 ruleset,我没有逐项核对)3。

回到开头

开头那个检查失败也能合并的仓库,是因为它一条规则都没有,只剩 draft 和冲突两条永远生效的卡点。对一个人的项目,这样大多数时候没问题,等到第一次遇见“各自是绿的、合在一起是红的”,就往表里下一行走一步。

小结

  1. 什么真能拦住合并? 只有 draft 和冲突永远生效。检查、评审、落后主干、部署状态,都要被分支规则点名后才拦。
  2. 保证改动本身没坏: 加 workflow,再设为必需检查。别给必需的 workflow 加路径过滤;检查跑在测试合并提交上,有冲突时不跑。
  3. 保证合进去以后也没坏: 打开与主干同步,代价是排队;PR 多了换合并队列,workflow 要加 merge_group。
  4. 保证该看的人看过: 必需评审加作废旧批准;有分区负责人再加 CODEOWNERS。draft 只是“先别看”的信号,不会让 CI 停下。
  5. 保证上线可控: 合并不等于部署。environment 审批拦部署 job,Require deployments to succeed 才拦合并。

如果想自己复现,实验 workflow 很短:在一个临时分支上放下面这个文件,开几个指向它的 PR,分别让检查失败、制造冲突、在 PR 里改 workflow,再看合并框的变化。

YAML
name: lab-gates
on:
pull_request:
branches: [lab/pr-gates-base]
types: [opened, synchronize, reopened, ready_for_review, closed]
pull_request_target:
branches: [lab/pr-gates-base]
push:
branches: [lab/pr-gates-base]
permissions:
contents: read
statuses: write
jobs:
info:
if: github.event.action != 'closed'
runs-on: ubuntu-latest
steps:
- run: |
echo "event=${{ github.event_name }} action=${{ github.event.action }}"
echo "GITHUB_SHA=$GITHUB_SHA GITHUB_REF=$GITHUB_REF"
echo "pr_head_sha=${{ github.event.pull_request.head.sha }}"
test:
if: github.event_name == 'pull_request' && github.event.action != 'closed'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: git log --oneline -1 && test ! -f FAIL
after-merge:
if: github.event.action == 'closed' && github.event.pull_request.merged
runs-on: ubuntu-latest
steps:
- run: echo "merged at ${{ github.event.pull_request.merge_commit_sha }}"

参考资料

Footnotes

  1. About pull requests(Draft pull requests 一节)GitHub Docsdocs.github.com ↗Draft pull requests cannot be merged, and code owners are not automatically requested to review them.https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests ↩ ↩2

  2. GraphQL enum MergeStateStatusGitHub Docsdocs.github.com ↗BEHIND、BLOCKED、CLEAN、DIRTY、DRAFT、HAS_HOOKS、UNKNOWN、UNSTABLE;REST 的 mergeable_state 是同一组值的小写。https://docs.github.com/en/graphql/reference/enums#mergestatestatus ↩

  3. About protected branchesGitHub Docsdocs.github.com ↗必需评审、必需检查(strict 要求与 base 同步)、会话解决、签名提交、线性历史、合并队列、部署成功、锁定分支、不许绕过等全部开关。https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches ↩ ↩2 ↩3 ↩4 ↩5

  4. About status checksGitHub Docsdocs.github.com ↗检查分两种:commit status(Statuses API)和 check run(Checks API,只有 GitHub App 能写,Actions 就是这样上报的)。https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collecting-information-about-changes-in-a-project/about-status-checks ↩

  5. Troubleshooting required status checksGitHub Docsdocs.github.com ↗被路径或分支过滤掉的 workflow,对应的必需检查一直 Pending;同名的 check 和 status 都要通过;必需检查要在最新提交上通过;if 跳过的 job 算 Success。https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks ↩

  6. Events that trigger workflowsGitHub Docsdocs.github.com ↗pull_request 默认类型 opened、synchronize、reopened;GITHUB_REF 为 refs/pull/N/merge;PR 有冲突时 pull_request 不运行;pull_request_target 在默认分支的上下文运行;合并后用 closed + merged 判断。https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows ↩ ↩2

  7. Managing a merge queueGitHub Docsdocs.github.com ↗入队的 PR 和最新 base 及前面排队的 PR 合在一起,推到 gh-readonly-queue/ 临时分支测试;workflow 必须监听 merge_group;失败、超时、冲突就出队,后面的重建。https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue ↩

  8. Pull request merge queue is now generally availableGitHub Changelog · 2023-07-12github.blog ↗可用范围:组织所有的公开仓库,以及 Enterprise Cloud 组织的私有仓库。https://github.blog/changelog/2023-07-12-pull-request-merge-queue-is-now-generally-available/ ↩

  9. Automatically merging a pull requestGitHub Docsdocs.github.com ↗仓库先开 Allow auto-merge;只在 PR 不能立即合并时出现;等必需评审和检查都通过后自动合并。https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request ↩

  10. About code ownersGitHub Docsdocs.github.com ↗用 base 分支上的 CODEOWNERS;最后匹配的模式优先;draft 不请求 code owner;只有开了 Require review from Code Owners 才是必需的。https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners ↩

  11. Managing environments for deploymentGitHub Docsdocs.github.com ↗必需审批人(最多 6 个)、禁止自审、等待计时、限定分支、App 自定义规则;job 引用不存在的环境会自动创建;规则通过前 job 不开始,也拿不到环境 secret。https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment ↩

  12. About rulesetsGitHub Docsdocs.github.com ↗多个 ruleset 可同时作用于同一分支,没有优先级,同一条规则取最严格的;和分支保护规则叠加;可设 bypass 列表和启用状态。https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets ↩