高度な `CODEOWNERS` 設定

CODEOWNERSファイルは、特定のファイルとディレクトリの担当者を定義するのに役立ちます。正規表現、セクション、および継承ルールを使用して、レビュアーをマージリクエストに割り当て、マージ前に承認を要求できます。

パターン

GitLabでは、パターンマッチングにFile::fnmatchとFile::FNM_DOTMATCHおよびFile::FNM_PATHNAMEフラグを設定して使用します:

リポジトリの構造は、分離されたファイルシステムのように扱われます。
パターンは、シェルのファイル名グロブ規則のサブセットに従い、正規表現ではありません。
File::FNM_DOTMATCHフラグを使用すると、*が.gitignoreのようなドットファイルに一致します。
File::FNM_PATHNAMEフラグは、*が/パスセパレーターに一致しないようにします。
**は、ディレクトリを再帰的に照合します。たとえば、**/*.rbはconfig/database.rbおよびapp/controllers/users/stars_controller.rbに一致します。

デフォルトのコードオーナーとオプションのセクション

既定のオーナーの構文をオプションのセクションおよび必須の承認と組み合わせるには、最後に既定のオーナーを配置します:

[Documentation][2] @docs-team
docs/
README.md

^[Database] @database-team
model/db/
config/db/database-setup.md @docs-team

通常エントリとセクション

セクション外のパスにデフォルトのコードオーナーを設定すると、常に承認が必要になります。このようなエントリは、セクションによってオーバーライドされません。セクションのないエントリは、別の名前のないセクションであるかのように扱われます:

# Required for all files
* @general-approvers

[Documentation] @docs-team
docs/
README.md
*.txt

[Database] @database-team
model/db/
config/db/database-setup.md @docs-team

この例では:

@general-approversは、オーバーライドなしですべての場所のすべてのアイテムを所有します。
@docs-teamは、Documentationセクション内のすべての項目を所有します。
@database-teamは@docs-teamを除くDatabaseセクションのすべての項目を所有しており、config/db/database-setup.mdにはに割り当てるオーバーライドがあります。
model/db/CHANGELOG.txtを変更するマージリクエストでは、@general-approvers、@docs-team、および@database-teamグループからそれぞれ1つずつ、3つの承認が必要になります。

この動作は、セクションの特定のエントリがセクションのデフォルトをオーバーライドする場合に、セクションの既定のオーナーのみを使用する場合と比較してください。

名前が重複しているセクション

複数のセクションに同じ名前が付けられている場合は、それらが結合されます。また、セクションヘッダーでは大文字と小文字が区別されません。例:

[Documentation]
ee/docs/    @docs
docs/       @docs

[Database]
README.md  @database
model/db/   @database

[DOCUMENTATION]
README.md  @docs

このコードの結果、Documentationセクションヘッダーの下に3つのエントリ、Databaseの下に2つのエントリが作成されます。DocumentationおよびDOCUMENTATIONセクションで定義されたエントリは、最初のセクションのケースを使用して結合されます。

特定のファイルとディレクトリのコードオーナーを定義する。

ファイルまたはディレクトリがCODEOWNERSファイル内の複数のエントリと一致する場合、ファイルまたはディレクトリに最後に一致したパターンからのユーザーが使用されます。これにより、エントリを適切な方法で順序すると、より具体的に定義されたファイルまたはディレクトリに対して、より具体的なオーナーを定義できます。

たとえば、次のCODEOWNERSファイルで説明します:

# This line would match the file terms.md
*.md @doc-team

# This line would also match the file terms.md
terms.md @legal-team

terms.mdのコードオーナーは@legal-teamになります。

コードオーナーからの複数の承認を必須にする。

マージリクエストの[承認]領域にあるコードオーナーセクションに対して、複数の承認を要求できます。セクション名に括弧で囲まれた数値n（[2]や[3]など）を追加します。これにより、このセクションのコードオーナーからのn承認が必要になります。nの有効なエントリは整数≥ 1です。[1]はデフォルトであるためオプションです。nの無効な値は1として扱われます。

イシュー384881では、この設定の動作の変更が提案されています。無効な値を意図的に設定しないでください。将来有効になり、予期しない動作が発生する可能性があります。

コードオーナーからの複数の承認を必須にする:

左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
設定 > リポジトリを選択します。
ブランチルールを展開する。
デフォルトのブランチの横にある詳細を表示を選択します。
コードオーナーの承認の下のトグルをオンにします。
CODEOWNERSファイルを編集して、複数承認のルールを追加する。

たとえば、[Documentation]セクションに2つの承認が必要な場合は、次のようにします:

[Documentation][2]
*.md @tech-writer-team

[Ruby]
*.rb @dev-team

[承認]領域のDocumentationコードオーナーセクションには、2つの承認が必要であることが表示されます:

グループの継承および資格

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
    accTitle: Diagram of group inheritance
    accDescr: If a subgroup owns a project, the parent group inherits ownership.
    A[Parent group X] -->|owns| B[Project A]
    A -->|contains| C[Subgroup Y]
    C -->|owns| D[Project B]
    A-. inherits ownership .-> D

この例では:

親グループX（group-x）はプロジェクトAを所有しています。
親グループXには、サブグループ、サブグループY（group-x/subgroup-y）も含まれています。
サブグループYは、プロジェクトBを所有します。

対象となるコードオーナーは次のとおりです:

プロジェクトA: プロジェクトAはサブグループYに属していないため、グループXのメンバーのみ。
プロジェクトB: グループXとサブグループYの両方のメンバー。

親グループにサブグループを招待

プロジェクトAの親グループにサブグループYを招待することはサポートされていません。サブグループYをコードオーナーとして設定するには、このグループをプロジェクトに直接招待します。

承認を必須にするには、コードオーナーとしてのグループは、プロジェクトで直接メンバーシップ（継承されたメンバーシップではない）を持っている必要があります。承認は、メンバーシップを継承するグループに対してのみオプションになります。コードオーナーグループのメンバーも、親グループからメンバーシップを継承するのではなく、直接メンバーである必要があります。

親グループのプロジェクトにサブグループを招待

メンバーも対象となるコードオーナーになるように、サブグループYをプロジェクトAに招待できます。

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph LR
    accTitle: Diagram of subgroup inheritance
    accDescr: Inviting a subgroup directly to a project affects whether their approvals can be made required.
    A[Parent group X] -->|owns| B[Project A]
    A -->|also contains| C[Subgroup Y]
    C -.->D{Invite Subgroup Y<br/>to Project A?} -.->|yes| E[Members of Subgroup Y<br/>can submit Approvals]
    D{Invite Subgroup Y<br/>to Project A?} -.->|no| F[Members of Subgroup Y<br />cannot submit Approvals]
    E -.->|Add Subgroup Y<br/> as Code Owner to Project A| I[Approvals can be<br/>required] -.-> B
    F -.-> |Add Subgroup Y<br/> as Code Owners to Project A| J[Approvals can only<br/>be optional] -.-> B

サブグループYをプロジェクトAに招待せずに、コードオーナーにすると、マージリクエストの承認はオプションになります。

エラー処理

スペースを含むエントリ

バックスラッシュを使用して、パス内の空白をエスケープします:

path\ with\ spaces/*.md @owner

エスケープしないと、GitLabはfolder with spaces/*.md @groupをpath: "folder", owners: " with spaces/*.md @group"として解析します。

解析できないセクション

セクションヘッダーを解析できない場合、セクションは次のようになります:

エントリとして解析されます。
前のセクションに追加されます。
前のセクションが存在しない場合、セクションはデフォルトセクションに追加されます。

デフォルトセクションの後

* @group

[Section name
docs/ @docs_group

GitLabは、ヘッダー[Section nameをエントリとして認識します。デフォルトセクションには、次の3つのルールが含まれています:

デフォルトセクション
- *オーナーは@group
- [Sectionオーナーはname
- docs/オーナーは@docs_group

名前付きセクションの後

[Docs]
docs/**/* @group

[Section name
docs/ @docs_group

GitLabは、ヘッダー[Section nameをエントリとして認識します。[Docs]セクションには、次の3つのルールが含まれています:

docs/**/*オーナーは@group
[Sectionオーナーはname
docs/オーナーは@docs_group

不正な形式のオーナー

各エントリには、1人以上のオーナーが含まれている必要があります。不正な形式のオーナーは無効になり、無視されます:

/path/* @group user_without_at_symbol @user_with_at_symbol

このエントリのオーナーは、@groupと@user_with_at_symbolです。

アクセスできない、または不適切なオーナー

GitLabは、アクセスできないオーナーまたは不適切なオーナーを無視します。例:

* @group @grou @username @i_left @i_dont_exist example@gitlab.com invalid@gitlab.com

@group、@username、およびexample@gitlab.comのみがアクセスできる場合、GitLabはその他を無視します。

ゼロオーナー

エントリにオーナーが含まれていない場合、またはアクセス可能なオーナーが存在しない場合、エントリは無効です。このルールは満たされることがないため、GitLabはマージリクエストで自動的に承認します。

保護ブランチでRequire code owner approvalが有効になっている場合、オーナーがゼロのルールは引き続き有効です。

最小承認

セクションの承認回数を定義する場合、最小承認回数は1です。承認の数を0に設定すると、GitLabは1つの承認を要求します。

高度な CODEOWNERS 設定