GitHub Branch Protection 怎麼轉 Repository Rulesets？先檢查風險與驗證流程

Branch Protection 和 Repository Rulesets 的差異#

兩者都能保護分支，但管理模型不同。Branch Protection 通常是一條規則對應一組分支；Rulesets 可以用 pattern 套用到多個分支，也能疊加多層規則。

GitHub 官方文件也提醒，Rulesets 和 Branch Protection 可以並存，而且所有適用規則都會被執行。因此，遷移期間暫時保留舊規則是安全的觀察手段，但不能把「兩邊都開著」當成最後狀態。

轉換前先盤點會被搬過去的設定#

GitHub 的轉換工具會把現有規則映射成對應的 ruleset。開始前，先把下面幾項從舊規則頁面記下來：

• required approving reviews 的數量、dismiss stale reviews 與 code owner review。
• required status checks 的名稱，以及是否要求 branch 必須是最新狀態。
• push restrictions、force push、branch deletion 和 signed commit 等限制。
• bypass actor、administrator 是否可以略過規則，以及部署 bot 是否依賴這個例外。
• 哪些 branch pattern 會命中這條規則，避免轉換後把範圍放大。

其中有一個不能直接一對一搬遷的例外：Require conversation resolution before merging。在 Branch Protection 中它是獨立設定；在 Rulesets 中則屬於 pull request rule 的一部分，必須同時啟用該類 pull request rule 才會套用。這是最值得在轉換預覽畫面再次核對的項目。

如果團隊目前有 required check 偶爾因 path filter 被 skipped，可以先看站內的 GitHub Actions required check 被跳過時的排查流程。那篇處理的是 check 狀態與 workflow 觸發邏輯；本篇處理的是分支治理規則如何搬遷，兩者不要混成同一個問題。

GitHub 的轉換流程怎麼走#

轉換是 repository 層級的管理操作，需要 repository admin 或具備 edit repository rules 權限的自訂角色。

1. 開啟 repository，進入 Settings。
2. 在左側 Code and automation 區段選擇 Branches。
3. 在 Branch protection rules 找到要搬遷的規則，點選 Convert to ruleset。
4. 為轉換產生的每個 ruleset 命名，閱讀 New behavior 預覽。
5. 確認規則範圍、required checks、review 和 bypass 後，選擇是否在完成遷移時刪除舊 Branch Protection。
6. 建立 ruleset，並在實際 PR 上驗證。

官方文件的建議是一次轉換一條 Branch Protection 規則。若一條舊規則會產生多個 rulesets，建立按鈕會顯示數量；不要只看到名稱相近就以為它一定是一對一的複製。

什麼時候可以刪除原本的 Branch Protection#

測試通過後回到 Branches 設定頁。如果新 ruleset 已完整涵蓋原規則，GitHub 會把原本的按鈕改成提示，表示這條 Branch Protection 可以安全刪除。這個提示是「目前映射看起來完整」的訊號，不是替你完成風險審核。

刪除前再做三個人工確認：

1. 新 ruleset 的 target branches 沒有比舊規則更廣或更窄。
2. bypass actor、GitHub App 和部署流程仍能在預期位置工作。
3. required checks 的 context 名稱沒有因 workflow 改名或分層而失效。

若團隊接著要把相同政策套到 organization 的多個 repository，可以在單一 repository 驗證完成後，再評估 organization-level rulesets。不要把一次成功的轉換直接複製到所有 repository，因為每個 repo 的 branch pattern、release bot 和 required checks 可能不同。

轉換後的治理重點#

Repository Rulesets 的價值不只是新介面。它讓規則可以分層、讓 active rulesets 對有讀取權限的開發者可見，也能把 bypass 權限明確指派給團隊與 App。這些特性適合拿來整理「誰能合併」和「哪些分支必須經過什麼檢查」的責任邊界。

但它仍然不是完整的 CI 安全策略。Ruleset 控制分支與標籤互動，不能取代 workflow 的 permissions、pull_request_target checkout 安全、environment reviewer 或第三方 action 的版本審查。若要限制的是「誰能讓 workflow 進入 runner」，那是 GitHub Actions workflow execution protections 的問題，不是 branch ruleset 的替代方案。

把規則搬到 Rulesets 後，最有用的維護紀錄至少應包含：轉換日期、原規則名稱、產生的 ruleset 名稱、保留或刪除舊規則的決定，以及測試過的 PR。未來有人看到合併被擋時，才知道要查哪一層政策。

常見問題#