コード オーナーの構文とエラー処理

このページでは、Code Ownersファイルで使用される構文とエラー処理について説明し、ファイルの例を示します。

コード・オーナーの構文

コメント

# で始まる行は無視されます：

# This is a comment

セクション

セクションはエントリーのグループです。セクションは角括弧のセクション見出しで始まり、エントリーが続きます。

[Section name]
/path/of/protected/file.rb @username
/path/of/protected/dir/ @group

セクションの見出し

セクション見出しには必ず名前を付けなければなりません。また、任意にしたり、承認者をいくつかにすることもできます。デフォルトのオーナーのリストをセクション見出しの行に追加することができます。

# Required section
[Section name]

# Optional section
^[Section name]

# Section requiring 5 approvals
[Section name][5]

# Section with @username as default owner
[Section name] @username

# Section with @group and @subgroup as default owners and requiring 2 approvals
[Section name][2] @group @subgroup

セクション名

セクション名は角括弧で囲んで定義します。セクション名は大文字小文字を区別しません。重複するセクション名は結合されます。

[Section name]

必須セクション

必須セクションには、セクション名の前に^ を付けません。

[Required section]

オプションのセクション

オプションのセクションには、セクション名の前に^ を付けます。

^[Optional section]

複数の承認者を必要とするセクション

複数の承認が必要なセクションには、セクション名の後に承認者数を角括弧で囲みます。

[Section requiring 5 approvals][5]
note
オプションのセクションは、必要な承認者数を無視します。

デフォルトのオーナーを持つセクション

セクション見出しにオーナーを追加することで、セクション内のエントリーのデフォルトオーナーを定義できます。

# Section with @username as default owner
[Section name] @username

# Section with @group and @subgroup as default owners and requiring 2 approvals
[Section name][2] @group @subgroup

コードオーナーエントリー

各コードオーナーエントリには、1人以上のオーナーがたどるパスが含まれています。

README.md @username1
note
セクション内でエントリーが重複している場合は、各セクションの最後のエントリーが使用されます。

相対パス

パスが/ で始まらない場合、そのパスはグロブスターで始まるものとして扱われます。README.md は/**/README.mdと同様に扱われます：

# This will match /README.md, /internal/README.md, /app/lib/README.md
README.md @username

# This will match /internal/README.md, /docs/internal/README.md, /docs/api/internal/README.md
internal/README.md

絶対パス

パスが/ で始まる場合、リポジトリのルートにマッチします。

# Matches only the file named `README.md` in the root of the repository.
/README.md

# Matches only the file named `README.md` inside the `/docs` directory.
/docs/README.md

ディレクトリパス

パスの末尾が/の場合、そのパスはディレクトリ内のどのファイルにもマッチします。

# This is the same as `/docs/**/*`
/docs/

ワイルドカードパス

ワイルドカードを使用すると、パスの複数の文字のいずれかに一致させることができます。

# Any markdown files in the docs directory
/docs/*.md @username

# /docs/index file of any filetype
# For example: /docs/index.md, /docs/index.html, /docs/index.xml
/docs/index.* @username

# Any file in the docs directory with 'spec' in the name.
# For example: /docs/qa_specs.rb, /docs/spec_helpers.rb, /docs/runtime.spec
/docs/*spec* @username

# README.md files one level deep within the docs directory
# For example: /docs/api/README.md
/docs/*/README.md @username

グローブスターのパス

Globstar (**) は、ゼロ個以上のディレクトリとサブディレクトリにマッチさせることができます。

# This will match /docs/index.md, /docs/api/index.md, /docs/api/graphql/index.md
/docs/**/index.md

エントリーのオーナー

エントリーには1つ以上のオーナーが必要です。これらはグループ、サブグループ、ユーザーのいずれでもかまいません。オーナーの順番は重要ではありません。

/path/to/entry.rb @group
/path/to/entry.rb @group/subgroup
/path/to/entry.rb @user
/path/to/entry.rb @group @group/subgroup @user

エントリーのオーナーとしてのグループ

グループおよびサブグループは、エントリのオーナーになることができます。各エントリーは、1 人以上のオーナーに所有させることができます。詳細については、「コード所有者としてグループを追加する」を参照してください。

/path/to/entry.rb @group
/path/to/entry.rb @group/subgroup
/path/to/entry.rb @group @group/subgroup

エントリーのオーナーとしてのユーザー

ユーザーはエントリーのオーナーになることができます。各エントリーは、1人または複数のオーナーに所有させることができます。

/path/to/entry.rb @username1
/path/to/entry.rb @username1 @username2

コード・オーナーのエラー処理

GitLab 16.3で導入されたエラー検証。

スペースを含む項目

空白を含むパスはバックスラッシュでエスケープする必要があります:path\ with\ spaces/*.md.バックスラッシュがない場合、最初の空白の後のパスはオーナーとしてパースされます。GitLab はfolder with spaces/*.md @group をpath: "folder", owners: " with spaces/*.md @group" にパースします。

パースできないセクション

セクションの見出しが解析できない場合、そのセクションは

  1. 項目として解析されます。
  2. 前のセクションに追加。
  3. 前のセクションが存在しない場合、そのセクションはデフォルトのセクションに追加されます。

例えば、このファイルには角括弧がありません：

* @group

[Section name
docs/ @docs_group

GitLabは見出し[Section name を項目として認識します。デフォルトのセクションには3つのルールがあります：

  • デフォルトセクション
    • * 所有者@group
    • [Section 所有者name
    • docs/ 所有者@docs_group

このファイルには、Section とname の間にエスケープされていないスペースがあります。GitLabは意図した見出しをエントリーとして認識します：

[Docs]
docs/**/* @group

[Section name]{2} @group
docs/ @docs_group

[Docs] セクションには3つのルールがあります：

  • docs/**/* 所有者@group
  • [Section 所有者name]{2} @group
  • docs/ 所有者@docs_group

不正なオーナー

各エントリには1つ以上のオーナーが含まれていなければなりません。例えば/path/* @group user_without_at_symbol @user_with_at_symbol は@group と@user_with_at_symbol によって所有されています。

アクセスできない、あるいは不正なオーナー

アクセスできないオーナーや不正確なオーナーは無視されます。たとえば、@group 、@username 、example@gitlab.com がプロジェクトでアクセス可能で、エントリを作成した場合：

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

GitLab は@grou,@i_left,@i_dont_exist,invalid@gitlab.comを無視します。

誰がアクセス可能かについての詳細は、コードオーナーとしてグループを追加するをご覧ください。

ゼロオーナー

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

note
保護されたブランチでRequire code owner approval が有効になっている場合でも、オーナーがゼロのルールは尊重されます。

必要な承認者が1人未満

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

CODEOWNERS ファイルの例 

# This is an example of a CODEOWNERS file.
# Lines that start with `#` are ignored.

# app/ @commented-rule

# Specify a default Code Owner by using a wildcard:
* @default-codeowner

# Specify multiple Code Owners by using a tab or space:
* @multiple @code @owners

# Rules defined later in the file take precedence over the rules
# defined before.
# For example, for all files with a filename ending in `.rb`:
*.rb @ruby-owner

# Files with a `#` can still be accessed by escaping the pound sign:
\#file_with_pound.rb @owner-file-with-pound

# Specify multiple Code Owners separated by spaces or tabs.
# In the following case the CODEOWNERS file from the root of the repo
# has 3 Code Owners (@multiple @code @owners):
CODEOWNERS @multiple @code @owners

# You can use both usernames or email addresses to match
# users. Everything else is ignored. For example, this code
# specifies the `@legal` and a user with email `janedoe@gitlab.com` as the
# owner for the LICENSE file:
LICENSE @legal this_does_not_match janedoe@gitlab.com

# Use group names to match groups, and nested groups to specify
# them as owners for a file:
README @group @group/with-nested/subgroup

# End a path in a `/` to specify the Code Owners for every file
# nested in that directory, on any level:
/docs/ @all-docs

# End a path in `/*` to specify Code Owners for every file in
# a directory, but not nested deeper. This code matches
# `docs/index.md` but not `docs/projects/index.md`:
/docs/* @root-docs

# Include `/**` to specify Code Owners for all subdirectories
# in a directory. This rule matches `docs/projects/index.md` or
# `docs/development/index.md`
/docs/**/*.md @root-docs

# This code makes matches a `lib` directory nested anywhere in the repository:
lib/ @lib-owner

# This code match only a `config` directory in the root of the repository:
/config/ @config-owner

# If the path contains spaces, escape them like this:
path\ with\ spaces/ @space-owner

# Code Owners section:
[Documentation]
ee/docs    @docs
docs       @docs

# Use of default owners for a section. In this case, all files (*) are owned by
the dev team except the README.md and data-models which are owned by other teams.
[Development] @dev-team
*
README.md @docs-team
data-models/ @data-science-team

# This section is combined with the previously defined [Documentation] section:
[DOCUMENTATION]
README.md  @docs