コード所有者には、リポジトリへの書き込み権限を持っている人を指定する必要があります。 コード所有者が Team である場合は、Team を表示できる必要があり、Team の個々のメンバーが直接書き込みアクセス許可を既に持っている場合でも、Organization のメンバーシップまたは別の Team メンバーシップを通じて、Team が書き込みアクセス許可を持っている必要があります。
コードオーナーについて
コードオーナーは、他者が所有するコードを変更するプルリクエストをオープンすると、自動的にレビューをリクエストされます。 コードオーナーはドラフトのプルリクエストのレビューを自動的にリクエストされません。 ドラフトの pull request の詳細については、「pull requests について」を参照してください。 コードオーナーはドラフトのプルリクエストのレビューを自動的にリクエストされません。 プルリクエストをドラフトに変換する場合、通知を既にサブスクライブしているユーザーは自動的にサブスクライブ解除されません。 詳しくは、「プルリクエストのステージの変更」を参照してください。
管理者あるいはオーナー権限を持つ誰かがレビュー必須を有効化した場合、作者がリポジトリ中でプルリクエストをマージできるための条件としてコードオーナーからの承認を必須とすることもできます。 詳しくは、「保護されたブランチについて」を参照してください。
ファイルにコードオーナーがいる場合、プルリクエストをオープンする前にコードオーナーを確認できます。 リポジトリでは、ファイルを参照し、 にカーソルを合わせると、ヒントとコード所有権詳細が表示されます。
CODEOWNERSファイルの場所
CODEOWNERS ファイルを使うには、コードのオーナーを追加するブランチにおいて、リポジトリの .github/、root または docs/ ディレクトリに、CODEOWNERS という名前の新しいファイルを作成します。 CODEOWNERS ファイルが複数の場所に存在する場合、GitHub はその順序でファイルを検索し、最初に見つけたファイルを使用します。
各CODEOWNERSファイルは、リポジトリ内の単一のブランチにコードオーナーを割り当てます。 したがって、異なるブランチに対して異なるコード所有者を割り当てることができます (たとえば、既定のブランチのコード ベースには @octo-org/codeowners-team、gh-pages ブランチ上の GitHub Pages サイトには @octocat)。
コードオーナーがレビューのリクエストを受け取るためには、CODEOWNERS ファイルがプルリクエストの base ブランチになければなりません。 たとえば、リポジトリの gh-pages ブランチ上 の .js ファイルのコード所有者として @octocat を割り当てた場合、 .js ファイルの変更に関する pull request がヘッド ブランチと gh-pages の間で開かれると、@octocat はレビュー要求を受け取ります。
CODEOWNERS とフォーク
レビュー要求をトリガーするには、pull request のベース ブランチからの CODEOWNERS のバージョンを使用します。 基本ブランチは、pull request がマージされた場合に pull request が変更するブランチです。
フォークからpull requestを作成し、ベース ブランチがアップストリーム リポジトリにある場合、pull request はアップストリーム リポジトリ内のそのブランチの CODEOWNERS ファイルを使用します。 ベース ブランチがフォーク内のブランチである場合、pull request はフォーク内のそのブランチの CODEOWNERS ファイルを使用しますが、これは、コード所有者が write のアクセス権を持つフォークに追加された場合にのみレビュー要求をトリガーします。
にカーソルを合わせてファイルの責任者であるユーザーを表示すると、どのリポジトリにあるブランチの CODEOWNERS ファイルからの情報が表示されます。
CODEOWNERS ファイルのサイズ
CODEOWNERS ファイルのサイズは、3 MB 未満でなければなりません。 この制限を超える CODEOWNERS ファイルは読み込まれません。つまり、コード所有者の情報は示されず、pull request での変更のレビューは、適切なコード所有者に要求されません。
CODEOWNERS ファイルのサイズを小さくするには、ワイルドカード パターンを使って複数のエントリを 1 つのエントリにまとめることを検討してください。
CODEOWNERSの構文
警告: gitignore ファイルには、CODEOWNERS ファイルでは "動作しない" いくつかの構文ルールがあります。
#で始まるパターンは、コメントではなくパターンとして扱われるように、\を使ってエスケープしても動作しない- パターンを否定するのに
!を使用しても動作しない - 文字範囲を定義するのに
[ ]を使用しても動作しない
CODEOWNERS ファイルでは、gitignore ファイルで使われているルールと同じルールのほとんどに従っているパターンを使います。 パターンの後には、標準の @username または @org/team-name 形式を使って、GitHub の 1 つ以上のユーザー名または Team 名が続きます。 ユーザーとチームは、チームのメンバーが既にアクセス権を持っている場合でも、リポジトリへの明示的な write アクセス権を持っている必要があります。
同じパターンを持つ複数のコード所有者を照合する場合は、すべてのコード所有者が同じ行に存在する必要があります。 コード所有者が同じ行にない場合、パターンは最後に言及したコード所有者のみ照合されます。
ほとんどの場合、アカウントに追加されたメール アドレスでユーザーを参照することもできます (例: user@example.com)。 メール アドレスを使って、マネージド ユーザー アカウント を参照することはできません。 マネージド ユーザー アカウント について詳しくは、GitHub Enterprise Cloud ドキュメントの「Enterprise Managed Users について」を参照してください。
GitHub では大文字と小文字を区別するファイル システムが使われているため、CODEOWNERS のパスでは大文字と小文字が区別されます。 CODEOWNERS は GitHub によって評価されるため、大文字と小文字が区別されないシステム (macOS など) であっても、CODEOWNERS ファイルのパスとファイルでは大文字と小文字が正しく使い分けられている必要があります。
CODEOWNERS ファイルのいずれかの行に無効な構文が含まれている場合、その行はスキップされます。 リポジトリ内の CODEOWNERS ファイルに移動すると、エラーが強調表示されていることがわかります。 リポジトリの CODEOWNERS ファイル内のエラーの一覧には、API からアクセスすることもできます。 詳しくは、「リポジトリの REST API エンドポイント」を参照してください。
存在しない、またはアクセスが不十分なユーザーまたはチームを指定した場合、コード オーナーは割り当てられません。
CODEOWNERS ファイルの例
# This is a comment.
# Each line is a file pattern followed by one or more owners.
# These owners will be the default owners for everything in
# the repo. Unless a later match takes precedence,
# @global-owner1 and @global-owner2 will be requested for
# review when someone opens a pull request.
* @global-owner1 @global-owner2
# Order is important; the last matching pattern takes the most
# precedence. When someone opens a pull request that only
# modifies JS files, only @js-owner and not the global
# owner(s) will be requested for a review.
*.js @js-owner #This is an inline comment.
# You can also use email addresses if you prefer. They'll be
# used to look up users just like we do for commit author
# emails.
*.go docs@example.com
# Teams can be specified as code owners as well. Teams should
# be identified in the format @org/team-name. Teams must have
# explicit write access to the repository. In this example,
# the octocats team in the octo-org organization owns all .txt files.
*.txt @octo-org/octocats
# In this example, @doctocat owns any files in the build/logs
# directory at the root of the repository and any of its
# subdirectories.
/build/logs/ @doctocat
# The `docs/*` pattern will match files like
# `docs/getting-started.md` but not further nested files like
# `docs/build-app/troubleshooting.md`.
docs/* docs@example.com
# In this example, @octocat owns any file in an apps directory
# anywhere in your repository.
apps/ @octocat
# In this example, @doctocat owns any file in the `/docs`
# directory in the root of your repository and any of its
# subdirectories.
/docs/ @doctocat
# In this example, any change inside the `/scripts` directory
# will require approval from @doctocat or @octocat.
/scripts/ @doctocat @octocat
# In this example, @octocat owns any file in a `/logs` directory such as
# `/build/logs`, `/scripts/logs`, and `/deeply/nested/logs`. Any changes
# in a `/logs` directory will require approval from @octocat.
**/logs @octocat
# In this example, @octocat owns any file in the `/apps`
# directory in the root of your repository except for the `/apps/github`
# subdirectory, as its owners are left empty. Without an owner, changes
# to `apps/github` can be made with the approval of any user who has
# write access to the repository.
/apps/ @octocat
/apps/github
# In this example, @octocat owns any file in the `/apps`
# directory in the root of your repository except for the `/apps/github`
# subdirectory, as this subdirectory has its own owner @doctocat
/apps/ @octocat
/apps/github @doctocat
CODEOWNERS とブランチの保護
リポジトリの所有者は、ブランチ保護ルールを更新して、変更されたコードが変更されたファイルの所有者によって確実にレビューされるようにすることができます。 ブランチ保護規則を編集し、「コード所有者からのレビューを要求する」 オプションを有効にします。 詳しくは、「保護されたブランチについて」を参照してください。
注: コード所有者のレビューが必要な場合、_いずれか_の所有者による承認があればこの要件を十分に満たせます。 たとえば、CODEOWNERS ファイルに次の行が含まれているとします。
*.js @global-owner1 @global-owner2
つまり、JavaScript ファイルへの変更は @global-owner1 または @global-owner2 によって承認できますが、_両方_による承認は必要ありません。
承認されていない変更からリポジトリを完全に保護するには、CODEOWNERS ファイル自体の所有者を定義する必要もあります。 最も安全な方法は、リポジトリの.githubディレクトリに CODEOWNERS ファイルを定義し、リポジトリ所有者を CODEOWNERS ファイル (/.github/CODEOWNERS @owner_username) またはディレクトリ全体 (/.github/ @owner_username) の所有者として定義することです。
ブランチ保護規則の代わりに、ルールセットを作成できます。 ルールセットには、状態など、ブランチの保護ルールよりもいくつかの利点があり、管理者アクセスを必要とせずに検出可能性が向上します。 同時に複数のルールセットを適用することもできます。 詳しくは、「ルールセットについて」を参照してください。