Skip to content
Published on

GitHub Branch Protection 実践ガイド: Rulesets、Merge Queue、CODEOWNERS

🇰🇷KO🇺🇸EN🇯🇵JA
Split View✨Start Quiz
Authors

GitHub Branch Protection 実践ガイド

はじめに

main を守る、という表現はシンプルですが、実際の運用では次のような問いに答える必要があります。

  • 誰が直接 push できるのか
  • どの check が本当に必須なのか
  • どのパスに誰の承認が必要なのか
  • 多数の PR が同時に流入しても target branch を健全に保てるか
  • hotfix 例外をどう扱うか

この記事では GitHub の公式ドキュメントをもとに、branch protection、rulesets、merge queue、CODEOWNERS を一つの運用モデルとして整理します。

Branch protection だけでは苦しくなる理由

従来の branch protection rule は今でも重要ですが、組織が大きくなると次の課題が出やすくなります。

  • 類似ルールを各リポジトリで繰り返し設定する必要がある
  • ブランチパターンが増えるほど例外管理が難しくなる
  • 組織共通ルールとリポジトリ個別ルールを分けにくい

この段階で rulesets の価値が高くなります。設定を単発のブランチ保護ではなく、再利用可能なポリシーとして扱えるからです。

Rulesets を政策の中心に置く

rulesets の本質は複雑化ではなく一貫性です。

実務的なレイヤリング

レイヤ例目的
組織共通force push 禁止、削除禁止、署名付き commit ポリシー最低限のガバナンス
重要ブランチrequired checks、review 数、merge queuemain と release の健全性確保
チーム/リポジトリCODEOWNERS、パス別 workflowサービス固有要件の反映

この構造なら、例外が必要になっても「どの層を、なぜ緩めたか」を説明しやすくなります。

Required checks は運用ゲートとして設計する

ありがちな失敗は次の二つです。

  • 必須 check が少なすぎて保護が弱い
  • 必須 check が多すぎて開発速度だけを落とす

良い required check は次の性質を持ちます。

  • 本当に merge を止める価値がある
  • 恒常的に flaky ではない
  • 実行時間が予測可能
  • 他の check と役割が重複しない

最小セットの例

  • lint
  • unit tests
  • integration test または smoke test
  • build
  • 組織として本当に止める意思がある security check

必要なのは「多い checks」ではなく「止める意味がある checks」です。

CODEOWNERS はレビュー経路の設計図

CODEOWNERS を単なる自動レビュー補助として使うのはもったいないです。実務では次の価値が大きいです。

  • 重要パスの責任を明確にする
  • 必須レビューを本当の ownership に接続する
  • チーム境界とコード構造のズレを見える化する

運用上のポイント

  • パターンを広げすぎない
  • ownership を定期的に見直す
  • 異動や休職で無効化した owner を放置しない

古い CODEOWNERS はガバナンスを強くするのではなく、レビュー遅延だけを増やします。

Merge queue の本質は直前検証

merge queue の価値は、単に順番待ちを作ることではありません。最新の target branch 状態に対して、マージ直前に再検証することです。

特に効果が高いのは次の環境です。

  • 長い check を持つ busy repository
  • 多数の PR が相互に影響する monorepo
  • 個別 PR は green なのに main が壊れがちなチーム

例外処理は先に定義しておく

厳しい保護だけがあり、例外プロセスが無いと、実際の障害時に見えない admin bypass が増えます。最低限、次を文書化すると安全です。

  • hotfix bypass を承認できるのは誰か
  • どの check までなら例外扱いできるか
  • bypass 後にいつ post-review を行うか
  • bypass の記録をどこに残すか

段階的 rollout

すべての制約を一度に有効化するのは危険です。安全な順序は次のようになります。

  1. 現在の merge フローと flaky checks を整理する
  2. required checks を最小セットから強制する
  3. CODEOWNERS を現実の ownership に合わせる
  4. main と release へ merge queue を導入する
  5. 共通ポリシーを rulesets に移す

運用チェックリスト

  • main への直接 push が禁止されているか
  • required checks は価値があり安定しているか
  • CODEOWNERS は現在の ownership を反映しているか
  • stale review dismissal が必要な保存庫で設定されているか
  • merge queue の対象ブランチが明確か
  • hotfix と admin bypass の手順が文書化されているか

よくあるアンチパターン

すべての check を required にする

品質向上よりも merge 遅延が目立つ構成になりがちです。

CODEOWNERS を組織図の写しとして扱う

コード変更の実態に合わない owner は承認経路を不必要に長くします。

merge queue なしで main への高頻度マージを許す

PR 数が増えるほど、個別 green だけでは不十分になります。

まとめ

GitHub の保護ポリシーの目的は開発速度を落とすことではなく、組織が本当に守りたい品質境界を merge 前に明確化することです。rulesets は再利用可能な政策を作り、CODEOWNERS は責任経路を示し、merge queue は最後の検証を強くします。

最良のガバナンスは、もっとも複雑なものではなく、チームが説明でき、維持でき、信頼できるものです。

References

Discuss on Twitter • View on GitHub