要約

  • CODEOWNERS はブランチとパスに結び付いた責任の振り分け設定であり、非ドラフトのプルリクエストが所有対象のコードを変えるとGitHubは該当所有者にレビューを依頼できる。
  • 結果はベースブランチ上のファイル、配置の優先順位、最後に一致したパターン、変更パス、所有者の権限に依存する。現在見えるファイルだけでは過去の結果は立証できない。
  • 設定、差分、依頼、レビュー応答、別個のマージ条件を分けて残すことで、静的な規則を出来事の証拠に取り違えない。

設定が語るのは宛先であって出来事ではない

「所有者がレビューした」という一文には、複数の未回答が隠れる。ベースはどのブランチだったか。どのパスが変更されたか。どのパターンが最終的に一致したか。名前のある利用者やチームは当時必要な権限を持っていたか。依頼は発行され、特定の差分に対する応答は残っているか。ファイルを表示することは、この連鎖を示すことではない。

GitHubは CODEOWNERS を、リポジトリのコードに責任を持つ個人またはチームを定義するためのファイルとして説明する。所有者のいるコードを非ドラフトのプルリクエストが変更すると、GitHubは自動でレビューを依頼する。ドラフトはレビュー可能な状態になるまで自動依頼の対象ではない。ここで保証されるのは注意を向けるための経路であり、判断が済んだことではない。

規則はベースブランチに依存する。各 CODEOWNERS ファイルは一つのブランチに対する所有者を定め、レビュー依頼にはプルリクエストのベースブランチにある版が使われる。フォークから上流へ向かう変更なら、上流のベースブランチのファイルが基準である。同じパッチでも main と保守ブランチでは異なる所有者に解決されうる。ヘッド側にあるファイルや、後日デフォルトブランチで閲覧したファイルは、その時の規則の代用品にならない。

配置にも順序がある。GitHubは .github/、ルート、docs/ の順に探し、最初に見つけたファイルを使う。三メガバイトを超えるファイルは読み込まれず、所有者情報も表示されず、依頼も行われない。リポジトリに文章が存在したことと、その文章が特定イベントのルーティングを実行したことは別の主張である。

最後の一致が責任の範囲を変える

パターンは加算されるように見えるが、GitHubでは最後に一致したパターンが優先される。全体を対象にする * があっても、その後の *.js はJavaScript変更について前者を置き換えられる。同じ行の複数所有者は同じパターンを共有するが、一致する別々の行に書けば後の行だけが効く。一般規則だけを引用して順序と対象パスを復元しなければ、依頼されていない相手へ責任を帰す危険がある。

パスは大文字小文字を区別する。構文が無効な行は無視される。存在しない、または十分なアクセスを持たない利用者やチームは所有者として割り当てられない。これは特定のリポジトリへの非難ではない。設定文が実際のイベント証拠になるには、有効性の条件も示さなければならないという意味である。

GitHubが CODEOWNERS 自体の所有者を定義することを勧めるのも重要だ。責任を配る規則には、その規則を誰が変更できるかという履歴が必要である。そうでなければ、アプリケーションコードの所有者を示していても、所有権方針を変えた経路は見えない。

レビューとマージ条件は別の面にある

GitHubは自動レビュー依頼と、コード所有者の承認をマージ前に必須にする設定を区別する。後者は管理者または所有者が別途有効にする。複数所有者が同じパターンに並ぶ場合、必須設定が有効なら一人の承認で足りることがある。したがって、ファイルに名前があるだけで全員が必須ゲートになるわけではない。

さらにrulesetとブランチ保護は同時に適用できる。該当する規則は集約され、同じ規則の設定が異なるとより厳しい方が有効になる。プルリクエスト、承認数、コード所有者レビュー、ステータスチェック、デプロイ成功、コメント解決、マージ方式、バイパス権限は、別々に構成できる条件である。GitHubは、必要なレビューが全て承認済みでも、同じヘッドコミットを指す別のオープンなプルリクエストに保留または却下のレビューがあればマージできない場合があると記す。

承認は重要な情報である。変更がマージ可能な状態に見えるというレビュー判断を示す。ただしそれは、すべての規則が評価され、すべての条件が通ったという一枚の完了証明ではない。

設定からレビューへの記録を残す

重要な主張には、プルリクエストID、ベースとヘッドのコミットまたはツリー参照、変更パス集合を残す。次に、ベースブランチで適用された CODEOWNERS の配置と内容の識別子、適用パターン、解決された所有者集合を記録する。今日のファイルへリンクするだけでは足りない。

その後にイベントを結ぶ。いつ依頼が出たか、誰がどの状態で応答したか、どの差分またはコミットを対象にしたかである。マージ可能性まで述べるなら、適用された保護規則やruleset、各条件の観測状態、記録されたバイパスを別に示す。結び目の証拠がなければ、説明はその手前で止める。これはGitHubへの新たな義務ではなく、現在の設定を過去の完全な証拠として扱わないための編集上の節度である。

出典

  1. GitHub Docs — About code owners
  2. GitHub Docs — Pull request reviews
  3. GitHub Docs — About rulesets
  4. GitHub Docs — Available rules for rulesets