本篇重點
- Target branches 與 Bypass list 的作用對象與例外權限機制
- Branch rules、Restrict deletions 與 Block force pushes 等分支保護設定
- Require a pull request before merging 相關審核條件與允許的合併方式
- Status checks、Deployments、Signed commits 等 CI/CD 與安全要求
- Code scanning、Code quality、Code coverage 及 Copilot code review 等品質管控機制
Branch Ruleset 是 GitHub Repository Rulesets 提供的分支管理機制，用來限制符合條件的 Branch 可以進行哪些操作。
目標分支與例外權限設定
Bypass list
- 功能：指定不受此 Ruleset 規則約束的角色、團隊、整合應用程式或使用者清單。
- 啟用效果：被加入此清單的對象可繞過全域保護限制。例如：將
Repository Admin加入清單後，該管理者可在受保護分支上直接執行變更而不受 Ruleset 阻擋。
Target branches
- 功能：定義此 Ruleset 所要套用與匹配的分支範圍。
- 啟用效果：系統僅對符合匹配條件的分支實施保護。例如：指定條件為
main或release/*時，規則只對指定名稱的分支生效。
Branch 保護規則
Restrict creations
- 功能：限制「誰」可以建立符合 Target branches 命名規則的新分支。
- 啟用效果：僅有 Bypass list 中的成員具備建立符合條件分支的權限。例如：非授權使用者執行
git push origin release/v1.0嘗試建立匹配分支時，GitHub 伺服器會拒絕該操作。
Restrict updates
- 功能：限制「誰」可以直接更新匹配分支的 Commit 歷史。
- 啟用效果：未在 Bypass list 中的使用者無法直接將本地 Commit 推送（Push）至目標分支。例如：執行
git push origin main時會收到遠端拒絕訊息。
Restrict deletions
- 功能：限制「誰」可以指定的目標分支被刪除。
- 啟用效果：僅 Bypass list 授權對象可執行刪除動作。例如：使用者執行
git push origin --delete main或於 GitHub 網頁介面點擊刪除按鈕時，系統會顯示權限不足。
Require linear history
- 功能：強制目標分支維持單一線性 Commit 歷史，禁止提交 Merge Commit。
- 啟用效果：系統將拒絕包含 Merge Commit 的推送或合併請求。例如：本地分支若使用
git merge main產生了合併節點，該次變更將無法推送至目標分支，僅允許採用 Rebase 或 Squash 合併。
Require deployments to succeed
- 功能：要求目標分支在更新前，必須先成功部署至指定的環境。
- 啟用效果：當 Pull Request 欲合併至目標分支時，指定的部署環境（如
Staging）必須回報成功狀態。若部署失敗，GitHub 會停用合併按鈕。
Require signed commits
- 功能：要求推送至目標分支的所有 Commit 必須具備可驗證的 GPG 或 SSH 數位簽署。
- 啟用效果：未經簽署的 Commit 拒絕寫入目標分支。例如：未配置
git config user.signingkey的本地變更在 Push 時會直接觸發拒絕。
Pull Request 審核機制
Require a pull request before merging
- 功能：強制所有程式碼變更必須透過 Pull Request 進行，禁止直接 Push。
- 啟用效果：目標分支完全關閉直接 Push 的權限，所有提交均需經由 PR 流程導入。
Required approvals
- 功能：設定 Pull Request 在允許合併前所需的最少 Approve（同意）審核數量。
- 啟用效果：設定數值為 2 時，PR 必須獲得至少兩位具權限審核者的 Approve，否則「Merge pull request」按鈕會維持停用狀態。
Dismiss stale pull request approvals when new commits are pushed
- 功能：當 Pull Request 推送新的 Commit 時，自動重置既有的 Approve 審核狀態。
- 啟用效果：只要 PR 追加了新的程式碼變更，先前已取得的 Approve 標記會立刻失效，必須重新發起審核。
Require review from specific teams
- 功能：指定特定團隊成員作為該分支 Pull Request 的強制審核者。
- 啟用效果：PR 必須包含指定團隊成員的 Approve 才能符合合併條件。
Require review from Code Owners
- 功能：依據 Repository 內的
CODEOWNERS檔案設定，強制要求檔案負責人進行審核。 - 啟用效果：若 PR 修改的檔案路徑匹配
CODEOWNERS中的規則，必須取得對應 Code Owner 的 Approve 方可合併。
Require approval of the most recent reviewable push
- 功能：確保最後一次 Commit 變更是由推送者以外的其他成員完成審核。
- 啟用效果：防止 PR 作者在獲得審核後自行追加 Commit 並直接合併。最後一次 Commit 的推送者無法審核自己所推送的內容。
Require conversation resolution before merging
- 功能：強制要求 PR 中所有程式碼行落的討論串（Conversation）必須全部標記為 Resolved。
- 啟用效果：只要 PR 內尚有未解決（Unresolved）的留言或討論，系統將阻擋合併操作。
Allowed merge methods
- 功能：限制 Pull Request 允許使用的合併模式（Merge commit, Squash, Rebase）。
- 啟用效果：GitHub PR 介面的合併下拉選單僅會提供已勾選的選項。例如：若僅勾選
Squash，選單中將隱藏Create a merge commit與Rebase and merge。
| Merge 方法 | 合併效果 |
|---|---|
| Merge commit | 建立一個新的 Merge Commit，保留完整分支歷史。 |
| Squash and merge | 將所有 Commit 合併為一個 Commit 後再 Merge。 |
| Rebase and merge | 將 Commit Rebase 到目標 Branch，再逐一加入，不建立 Merge Commit。 |
狀態檢查與強推限制
Require status checks to pass
- 功能：要求指定的 CI/CD 自動化檢查（Status Checks）必須通過後才允許更新或合併分支。
- 啟用效果：未通過指定檢查（如單元測試或 Linter）前，分支更新會被系統阻擋。
健忘筆記
Status Checks 通常來自 GitHub Actions 或其他 CI 工具，檢查環境建置、單元測試、Lint、Security Scan 等。
Require branches to be up to date before merging
- 功能：要求 PR 分支必須整合目標分支的最新程式碼後才能進行合併。
- 啟用效果：若目標分支在 PR 建立後產生了新的 Commit，PR 作者必須先將目標分支最新版本 Rebase 或 Merge 至 PR 分支，並重新通過狀態檢查後才可合併。
Do not require status checks on creation
- 功能：建立符合 Ruleset 的新 Branch 時，不要求立即通過 Status Checks。
- 啟用效果：建立新分支的動作（例如建立 feat/xxx）不受限於預先存在的 Status Check 限制。
Block force pushes
- 功能：禁止對目標分支執行強制推送（
git push --force或git push --force-with-lease）。 - 啟用效果：任何試圖覆寫或重構目標分支 Commit 歷史的指令均會被 GitHub 伺服器拒絕。
程式碼審核與 AI 審核機制
Require code scanning results
- 功能：要求指定的靜態程式碼分析工具（如 CodeQL）完成掃描的結果必須符合預設的安全門檻。
- 啟用效果：若分析工具回報高於設定門檻（例如 Security alerts 設定為
High or higher、Alert 設定為Errors）的安全漏洞，系統將阻擋分支更新/合併。
健忘筆記
開啟設定後，GitHub 不會自動幫忙檢查程式碼，此設定是新增「審查條件」，沒有掃描結果就不能合併或更新，如需快速新增掃描功能，可到設定的 Advanced Security - Code scanning 有 Default Setup 可以使用
Require code quality results
- 功能：設定程式碼品質檢測工具（Code Quality Analysis）阻擋合併的最低嚴重性等級（Severity Level）。
- 啟用效果：當檢測報告出現達到或超過設定等級（例如
Errors）的品質問題時，系統將阻擋分支更新/合併。
健忘筆記
開啟設定後，GitHub 不會自動幫忙檢查程式碼，此設定是新增「審查條件」，沒有檢測結果就不能合併或更新，如需新增掃描功能，必須設定 Action（或透過其他 CI 工具）來產生成果
Restrict code coverage
- 功能：要求 PR 必須滿足預設的測試覆蓋率門檻或允許的最大降幅。
Minimum coverage percentage：設定絕對門檻（如 80%），覆蓋率低於此數值將阻擋合併。Maximum coverage drop：設定允許相較於目標分支的最大覆蓋率下降百分比（如 0%），若 PR 導致覆蓋率下降超過該數值則阻擋合併。- 啟用效果：當 Coverage 資料未達設定標準時，PR 頁面顯示測試覆蓋率未達標並停用合併功能。
Automatically request Copilot code review
- 功能：自動觸發 GitHub Copilot 對 Pull Request 進行 AI 程式碼審查。
Review new pushes：每次 PR 有新的 Commit 推送時，Copilot 自動執行差異比對審核。Review draft pull requests：對於草稿狀態（Draft）的 PR，Copilot 在標記為 Ready for review 前即預先進行審核。- 啟用效果：PR 建立或更新時，系統自動將 GitHub Copilot 指派為 Reviewer 並生成審查意見報告。
健忘筆記
Copilot Code Review 背後需要 AI 算力與服務，系統會檢查專案擁有者或組織是否有生效中的 Copilot 訂閱，確認授權才會開始 Code Review，不然不會有任何動作
結論
GitHub Branch Ruleset 提供了一套結構化且具備高度彈性的分支保護機制。透過 Target branches 與 Bypass list 的組合，能精準指定規則的套用對象與例外權限；結合 Pull Request 審核機制、Status checks 狀態檢查、Code scanning 及 Copilot code review 等自動化工具，可於 Commit 推送與合併階段實施強制驗證，確保程式碼歷史的完整性與安全性！
