開啟一個 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 }}"參考資料
參考資料
-
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 ↩