打开一个 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;没被点名的,只是摆在那里给人看。
所以理清这些东西,关键不是记住每个开关,而是先回答一个问题:合并到主干之前,你想保证什么? 归纳下来只有四种保证,后面四节一节讲一种,每种都回答三件事:不开会出什么事、最少开哪几样、开了要付出什么。
- 这次改动本身没坏:检查,并把它设为必需;
- 合进去以后主干也没坏:与主干同步,或合并队列;
- 该看的人看过:必需评审和 CODEOWNERS;
- 上线是可控的:部署环境和它的审批。
二、保证一:改动本身没坏
不开会怎样
最常见的事故是“忘了跑一下”:改了一行配置,本地没构建就推上去合了,主干从此构建失败。给仓库加一个在 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 被路径过滤,没运行 | 可合并 | 一直等待,永远合不了 |
| 只在旧提交上通过 | 可合并 | 不算数,要在新提交上重跑 |
“可合并”指检查这一项不拦;评审、冲突等其他条件另算。
被路径过滤掉的那一行最常见: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=openedGITHUB_SHA=bef7b38723f09a4ef78fb74d9845f29b0ece00a5GITHUB_REF=refs/pull/N/mergepr_head_sha=e796c534c1291c1193570d0a3a00f7ddfbb4d347跑的不是 PR 的 head 提交 e796c53,而是 GitHub 在后台把它合进主干得到的测试合并提交 bef7b386。也就是说,检查测的是“如果现在合并,主干会变成什么样”,跑完再把结果挂回 head 提交。
这带来两个后果。一是 PR 里改 workflow 文件会立刻生效:PR D 把 workflow 里的版本号改成 v2-head,它的运行打印的就是 v2-head。二是有冲突时检查不会跑:PR C 和主干冲突后再推一个提交,一个 workflow 都没触发,因为测试合并提交生成不出来。所以看到“检查一直不动”,先看看是不是有冲突。
检查测的是“合并后的样子”,可这个样子是拿当时的主干算的。主干往前走了,这个绿色还算数吗?
三、保证二:合进去以后主干也没坏
不开会怎样
这是实验里最能说明问题的一段:
- PR A 打开,检查在
bef7b38(PR A 合进旧主干236b111)上通过。 - PR B 带着一个会让测试失败的
FAIL文件合进了主干,主干变成77f0799。 - PR A 转为 ready for review,又跑了一次,用的仍是旧的
bef7b38,依然通过。 - PR A 再推一个提交,新的测试合并提交
aeaa0d5基于77f0799,带上了FAIL,检查失败。
PR A 自己什么都没做错。但在第 2 步到第 4 步之间,它挂着一个绿色的结果,而这个结果测的是一个已经不存在的主干。这时候点合并,主干就会坏掉。两个 PR 各自都是绿的,合在一起却是红的,这就是“保证一”管不到的地方。第 3 步还说明测试合并提交是后台异步重算的,事件到来时未必已经更新(这是根据日志推断的,文档没写重算时机)。
最少开什么:与主干同步
在必需检查的规则里勾上 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 踢出去,后面的重建。
它有两个前提。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 Owners | CODEOWNERS 只负责发评审请求 | 改到谁的文件,必须有对应 owner 批准 |
| Require approval of the most recent push | 作者推完最后一下自己就能凑齐 | 最后一次推送必须由推送者以外的人批准 |
| Require conversation resolution | 评审意见没处理也能合 | 所有评审对话标记为已解决才能合 |
管理员默认可以绕过,除非同时勾上 Do not allow bypassing the above settings。
最常一起开的是前两项:至少一人批准,有新推送就作废旧批准。后两项适合对安全要求更高的仓库。
有分区负责人: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。
反过来,如果希望“预发环境部署成功”是合并的前提,就在分支规则里打开 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 和冲突两条不用配,任何场景都生效。
规则写在哪
这些开关可以写在分支保护规则里,也可以写在 ruleset 里12。一个分支同时只受一条分支保护规则管;ruleset 则可以多条叠加,同一项取最严格的值,还能单独停用、给某些角色设置绕过,有读权限的人都能看到。新配置建议直接用 ruleset。需要注意,在免费计划下,这两种规则都只能用于公开仓库,私有仓库要升级计划(个人 Pro 的私有仓库能否用 ruleset,我没有逐项核对)3。
回到开头
开头那个检查失败也能合并的仓库,是因为它一条规则都没有,只剩 draft 和冲突两条永远生效的卡点。对一个人的项目,这样大多数时候没问题,等到第一次遇见“各自是绿的、合在一起是红的”,就往表里下一行走一步。
小结
- 什么真能拦住合并? 只有 draft 和冲突永远生效。检查、评审、落后主干、部署状态,都要被分支规则点名后才拦。
- 保证改动本身没坏: 加 workflow,再设为必需检查。别给必需的 workflow 加路径过滤;检查跑在测试合并提交上,有冲突时不跑。
- 保证合进去以后也没坏: 打开与主干同步,代价是排队;PR 多了换合并队列,workflow 要加
merge_group。 - 保证该看的人看过: 必需评审加作废旧批准;有分区负责人再加 CODEOWNERS。draft 只是“先别看”的信号,不会让 CI 停下。
- 保证上线可控: 合并不等于部署。environment 审批拦部署 job,Require deployments to succeed 才拦合并。
如果想自己复现,实验 workflow 很短:在一个临时分支上放下面这个文件,开几个指向它的 PR,分别让检查失败、制造冲突、在 PR 里改 workflow,再看合并框的变化。
name: lab-gateson: 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: writejobs: 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
-
About pull requests(Draft pull requests 一节)docs.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
-
GraphQL enum MergeStateStatusdocs.github.com ↗BEHIND、BLOCKED、CLEAN、DIRTY、DRAFT、HAS_HOOKS、UNKNOWN、UNSTABLE;REST 的
mergeable_state是同一组值的小写。https://docs.github.com/en/graphql/reference/enums#mergestatestatus ↩ -
About protected branchesdocs.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
-
About status checksdocs.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 ↩
-
Troubleshooting required status checksdocs.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 ↩ -
Events that trigger workflowsdocs.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 -
Managing a merge queuedocs.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 ↩ -
Pull request merge queue is now generally availablegithub.blog ↗可用范围:组织所有的公开仓库,以及 Enterprise Cloud 组织的私有仓库。https://github.blog/changelog/2023-07-12-pull-request-merge-queue-is-now-generally-available/ ↩
-
Automatically merging a pull requestdocs.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 ↩
-
About code ownersdocs.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 ↩
-
Managing environments for deploymentdocs.github.com ↗必需审批人(最多 6 个)、禁止自审、等待计时、限定分支、App 自定义规则;job 引用不存在的环境会自动创建;规则通过前 job 不开始,也拿不到环境 secret。https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment ↩
-
About rulesetsdocs.github.com ↗多个 ruleset 可同时作用于同一分支,没有优先级,同一条规则取最严格的;和分支保护规则叠加;可设 bypass 列表和启用状态。https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets ↩