コンテンツへスキップ

CODEOWNERS とブランチ保護のベストプラクティス

最終更新日

CODEOWNERSは、どのファイルを誰がレビューすべきかを定めます。ブランチ保護(またはルールセット)は、mainにコードを反映する前に何が満たされている必要があるかを定めます。両者を回避されないように設定すれば、組み合わせて最も低コストで品質とセキュリティを確保できる仕組みになります。本ガイドでは、構文と重要な設定について説明します。

CODEOWNERSの仕組み

CODEOWNERSファイルは、パスのパターンとユーザーまたはチームを対応付けます。GitHubは.github/、リポジトリのルート、docs/の順にこのファイルを探し、最初に見つかったものを使用します。PRが一致するファイルを変更すると、GitHubは記載されたオーナーにレビューを自動的に依頼します。ブランチ保護でコードオーナーのレビューが必須になっている場合、オーナーの承認がなければPRはマージできません。

# Default owners for everything
*                       @acme/platform

# Frontend
/web/                   @acme/frontend
*.css                   @acme/frontend @acme/design

# Backend and database
/services/api/          @acme/backend
/db/migrations/         @acme/backend @acme/dba

# CI and security-sensitive files
/.github/               @acme/platform @acme/security
/infra/                 @acme/platform
Dockerfile              @acme/platform

GitHubのドキュメントに基づくルールは次のとおりです。

  • 最後に一致したパターンが優先されます。一般的なものから具体的なものの順に記述してください。2つの行に一致するファイルには、後の行のオーナーのみが適用され、両方が適用されるわけではありません。
  • パターンは.gitignoreのルールに従いますが、例外があります。!による否定は使用できず、[ ]による文字範囲指定もサポートされていません。
  • オーナーには、@username、@org/team-name、またはアカウントに紐づいたメールアドレスを指定できます。
  • オーナーはリポジトリへの書き込み権限を持っている必要があります。チームの場合は、表示可能であり、書き込み権限を持っている必要があります。そうでない場合、その行は無視されます。
  • 3 MBを超えるファイルは読み込まれません。
  • 無効な行は、ファイル表示画面のエラー一覧で示されます。編集後は必ず確認してください。

CODEOWNERSジェネレーターで初期ファイルを作成し、その後はレビュアーの視点で内容を確認してください。

個人ではなくチームを指定する

個人は退職や休暇で不在になったり、作業のボトルネックになったりします。チームを割り当て、チームの設定でGitHubのチームレビュー割り当て機能(ラウンドロビンまたは負荷分散)によって、メンバーの一人または複数人を選ばせてください。非常に大規模なチームでは、全員に通知が行かないように「自動割り当て」を有効にしてください。

すべてのPRに対応できる人が必ずいるよう、オーナーの範囲は十分に広くしてください。一方で、意味を持つ程度には絞り込んでください。すべてのPRに5件の承認が必要なファイルは、形式的な承認を助長してしまいます。

攻撃者が狙うパスを保護する

信頼できるチームに次のものの所有権を与えてください。

  • /.github/、特に/.github/workflows/。ワークフローの変更はシークレットへアクセスしたりデプロイを実行したりできるため、GitHub Actionsのセキュリティ確保を参照してください。
  • CODEOWNERS自体。オーナーでない人がルールを変更できないようにするためです。
  • サプライチェーンのレビューが重要な場合は、依存関係のマニフェストとロックファイル。
  • インフラストラクチャのコード、認証と課金のロジック、マイグレーション。

ブランチ保護かルールセットか?

ルールセットは新しい仕組みです。複数の設定を重ねられ、パターンで多数のブランチに適用でき、組織全体で機能し、監査されるバイパスリストを持てます。ブランチ保護ルールは古い仕組みですが、現在もサポートされています。いずれの場合も、mainとリリースブランチに次の設定を行うことをおすすめします。

設定推奨理由
マージ前にプルリクエストを必須にする有効直接のプッシュを禁止する
必要な承認数1、機密性の高いリポジトリでは2すべての変更でレビューを行う
新しいコミット時に古い承認を取り消す有効承認は、マージされるコードを対象とすべきです
コードオーナーのレビューを必須にする有効CODEOWNERSを拘束力のあるものにします
最新のプッシュの承認を必須にする有効承認後に作成者がコミットを追加して自己マージすることを防ぎます
ステータスチェックを必須にする有効にし、必須のチェックを指定するCIの成功を必須にします
ブランチを最新の状態にすることを必須にするオンにする、またはマージキューを使用するセマンティックな競合を回避します
会話の解決を必須にする有効コメントに必ず返信されるようにします
署名付きコミットを必須にする任意一部のコンプライアンス規制で必要となります
線形履歴を必須にする任意スカッシュまたはリベースマージに合わせられます
強制プッシュと削除をブロックする有効履歴を保護する
バイパスを許可しない管理者を含め、全員に対して有効にします「管理者による上書きを許可」は、最悪のタイミングで使われがちです

必須チェックは少数で安定したものにしてください。テスト、リント、ビルド、セキュリティスキャンが対象です。単一のサマリージョブを通じて名前を指定すると、マトリックスのセルの名前を変更してもルールが壊れません。詳しくはマトリックスビルドの正しい使い方を参照してください。pathsフィルターでスキップされた必須チェックは永遠に保留のままになるため、ワークフローで対処してください。

よくある失敗パターンを避ける

  • メンテナーが1人だけのリポジトリでのコードオーナーレビュー。作成者は自分のPRを承認できないため、オーナーが1人だけだと手詰まりになります。オーナーを2人目に追加するか、少なくとも2人からなるチームを使用してください。
  • リポジトリの書き込み権限リストにないオーナー。その行は警告なく無視されます。
  • ** catch-all with a huge team.* Everyone is requested on every PR, so nobody feels responsible.
  • ボット。DependabotやRenovateのPRにもオーナーが必要なので、手詰まりにならないようにしてください。ローテーションする依存関係オーナーのチームに振り分け、リスクの低い更新には自動マージを使用します。詳しくはDependabotのセットアップを参照してください。
  • 不安定な必須チェック。管理者によるバイパスが使われるようになってしまいます。不安定さを解消してください。詳しくは不安定なテストへの対処を参照してください。
  • 増え続けるバイパスリスト。四半期ごとに見直してください。

それに伴うレビューの運用習慣

  • PRは小さく保ってください。大きな差分は、読まれないまま承認されがちです。
  • リスクの高いパスについてのチェックリストを含むPRテンプレートを追加してください。
  • レビューの待ち時間を計測してください。レビューが遅いと提供までのリードタイムが延びます。これはDORAメトリクスの1つです。
  • リスクの高いパスにはオーナーによる必須レビューを、ドキュメントにはより軽いプロセスを使用してください。CODEOWNERSでこれを表現できます。ドキュメントは幅広いチームに割り当ててください。

テストする

ルールを変更したら、保護対象の各領域に触れる使い捨てのPRを作成し、適切な担当者がレビュー依頼されること、マージボタンがブロックされることを確認してください。CODEOWNERSファイルの表示画面では、GitHubが構文エラーを表示します。まずそれらを修正してください。

よくある質問

CODEOWNERSファイルはどこに置くべきですか?

一般的には.github/CODEOWNERSに置きます。GitHubはリポジトリのルートやdocs/にあるファイルも読み取ります。

1つのファイルに複数のオーナーを指定できますか?

はい。1行に複数のオーナーを並べられます。別々の要件をルールセットで作成しない限り、コードオーナーの要件は、全員ではなく、そのうちの誰か1人の承認で満たされます。

コードオーナーのルールはPRの作成者にも適用されますか?

PRを作成したオーナーは自分でそのPRを承認できないため、別のオーナーが承認する必要があります。

この設定が必要なのはmainブランチだけですか?

デプロイを行うブランチ、たとえばrelease/*やproductionも保護してください。ブランチパターンを指定したルールセットなら、1か所でまとめて設定できます。

この設定と合わせてDependabotガイドを参照し、更新PRにもオーナーが割り当てられるようにしてください。必須チェックを高速化すると、人々がプロセスに沿って作業しやすくなります。compiler.devの比較モードでは、より高速なランナーで必須チェックがどれだけ速く実行されるかを確認できます。

このワークフローを compiler.dev で実行する カード登録不要 · 200 無料分

無料で試す