一條分支要穿過幾道閘門才能回到主幹 左邊是 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 }}"

參考資料

參考資料

  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 ↩