codeowners

codeowners

CODEOWNERS ファイルを作成・管理し、そのルールセットルールを有効にして、必須のレビュー要件として機能させます。

このスキルで扱うのは1つのファイルと、そのファイルが適用されるルールです。ブランチのルールセット全般（/gh-bootstrap）やコミュニティの健全性に関するファイル（/oss-hygiene）は設定しません。

使用する場面

• ユーザーが CODEOWNERS ファイルの追加や更新を依頼した場合。
• ユーザーがあるパスの所有者を尋ねた場合、または git の履歴に基づく所有者の候補を求めた場合。
• ユーザーがプルリクエストで所有者のレビューを必須にするよう求めた場合。
• ユーザーが既存の CODEOWNERS ファイルの検証を求めた場合。

手順

1. 既存ファイルとデフォルトブランチを確認する

GitHub は、次の3か所から順に CODEOWNERS を読み込みます。.github/、リポジトリのルート、次に docs/ です。最初に見つかったファイルのみが有効になります。

for path in .github/CODEOWNERS CODEOWNERS docs/CODEOWNERS; do
  test -f "$path" && echo "Found: $path"
done
REPO="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
DEFAULT_BRANCH="$(gh repo view "$REPO" --json defaultBranchRef --jq '.defaultBranchRef.name')"

複数の場所にファイルがある場合は、最初に一致したファイル（.github/、次にルート、次に docs/）のみが有効であることをユーザーに伝え、どのファイルを残すか確認します。 どこにもない場合は、作成する場所を確認します。リポジトリのポリシーファイルをまとめられるため、通常は .github/CODEOWNERS が選ばれます。

2. 所有者の根拠を集める

次の2つの方法を提示します。結果は候補として提示し、ルールを書く前にユーザーに確認します。所有者を自動的に割り当ててはいけません。

ディレクトリ構造に基づく方法。 最上位と第2階層のディレクトリを、所有範囲の候補として一覧表示します。

git ls-files | awk -F/ 'NF>1 {print $1"/"$2"/"} NF==1 {print $1}' | sort -u

コミッターに基づく履歴からの方法。 指定されたパスについて、コミット数の多い順にコントリビューターを並べ、重複のない作成者を一覧表示します。

git shortlog -sn -- <path>
git log --format=%an -- <path> | sort -u

最もコミット数の多い人は候補であり、決定ではありません。ファイルに記載する前に、候補者の名前またはメールアドレスを GitHub ハンドルまたはチームに対応付けてください。有効な GitHub ユーザー、または書き込みアクセス権を持つチームに解決されない CODEOWNERS のエントリーは、エラーではなく GitHub によって黙って無視されます。

3. ルールを作成する

ユーザーが確認した順序で、CODEOWNERS の構文に従ってルールを記述します。

• 最後に一致したパターンが優先されます。 一般的なルールを先に、具体的な上書きルールを後に並べます。ファイルに適用されるのは、最初ではなく最後に一致した行です。
• @org/team には書き込みアクセス権が必要です。 チームへの参照が有効になるのは、そのチームが組織のメンバーであるだけでなく、リポジトリへの書き込みアクセス権を明示的に付与されている場合に限られます。行を書く前に、チームが存在することを確認し、その後、書き込みアクセス権も確認します（「ガードレール」を参照）。
• 末尾の * によるフォールバックルール（* @org/default-owners）は、他のルールに一致しないパスに適用されます。より具体的なルールで上書きできるよう、先頭に記述します。
• パスのパターンは .gitignore の構文に従います。/dir/ はリポジトリのルートを基準にし、先頭にスラッシュのない dir/ は場所を問わず一致し、*.ext は拡張子で一致します。範囲を限定しない限り、ディレクトリはその配下にも再帰的に一致します。
• コメントは # で始まります。# Frontend のようなセクション見出しで関連ルールを読みやすくまとめられます。また、#SECTION_NAME ブロックとして記述すると、GitHub はファイルのレビューユーザーインターフェースでセクションを名前付きグループとして表示します。

構文と優先順位の詳細は references/syntax.md を、ひな形は assets/CODEOWNERS.example を参照してください。

書き込む前に、既存ファイルと提案内容の差分を確認し、ユーザーに提示します。黙って上書きしてはいけません。

4. 検証する

ファイルをデフォルトブランチにプッシュした後、GitHub で構文と所有権に関するエラーを確認できます。

gh api "repos/$REPO/codeowners/errors"

ここで 404 が返る場合、デフォルトブランチ上の有効な3か所のいずれにも CODEOWNERS ファイルが見つかっていません。先にプッシュしてから再確認してください。errors 配列が空の 200 は、ファイルが有効であることを示します。空でない場合は、該当する行と問題（不明なユーザー、書き込みアクセス権のないチーム、不正なパターン）が示されます。

プッシュ前のローカルでの簡易チェックとして、ルールの対象となるパスがツリー内に実際に存在することを確認します。

git ls-files -- '<path pattern from the rule>'

結果が空の場合、そのルールのパターンに一致する追跡対象がありません。多くの場合、これはタイプミスです。

5. ルールセットルールで強制する

CODEOWNERS はレビューを依頼するだけで、マージをブロックしません。 コードオーナーによる承認レビューを必須にするには、デフォルトブランチの ルールセットの pull_request ルールで require_code_owner_review: true を設定する必要があります。

gh api "repos/$REPO/rulesets" --jq '.[] | select(.target=="branch") | {id, name}'
gh api "repos/$REPO/rulesets/<id>" --jq '.rules[] | select(.type=="pull_request")'

現在の pull_request ルールのパラメーターと、提案する変更（require_code_owner_review: true）を ユーザーに提示し、書き込みの前に明示的な承認を得てください。

gh api -X PUT "repos/$REPO/rulesets/<id>" --input "$TMPDIR/ruleset.json"

パラメーター一式と、補完的な必須レビュアーのルールセットルール（GA 2026-02-17）については、 references/enforcement.md を参照してください。このルールは、CODEOWNERS に関係なく、 パスパターンを対象に特定のチームからの承認を必須にします。GitHub のドキュメントでは、 このルールは CODEOWNERS を置き換えるのではなく、補完するものとして説明されています。 CODEOWNERS は引き続きレビュー担当者の自動依頼を行い、必須レビュアーのルールは ルールセットレベルでポリシーを強制します。選択肢として案内してください。ユーザーから 依頼されない限り、有効にしないでください。

6. 確認して報告する

• CODEOWNERS ファイルの場所と内容が、ユーザーの確認した内容と一致していること。
• gh api repos/$REPO/codeowners/errors が空の errors 配列を返すこと（ファイルがまだプッシュされていない場合は、404 の理由を説明してください）。
• すべての @org/team 参照について、書き込みアクセス権があることを確認済みであること。
• ルールセットの pull_request.require_code_owner_review の値が、承認された内容と一致していること（ユーザーが強制を拒否した場合は、スキップしたことを報告してください）。

ガードレール

• 既存の CODEOWNERS ファイルを上書きする前に差分を確認し、ユーザーが確認していない内容を置き換える場合は事前に尋ねてください。
• GitHub のハンドルやチームスラッグを決して作り上げないでください。ルールに @org/team を追加する前に、gh api -H 'Accept: application/vnd.github.v3.repository+json' orgs/{org}/teams/{slug}/repos/$REPO を実行してください。.permissions.push が true であることを確認してください。404 は、チームが存在しない、アクセス権がない、 または使用しているトークンから見えないことを意味します。アクセス権の付与を依頼する前に、 gh api orgs/{org}/teams/{slug} でスラッグを確認してください。
• 特定の書き込みについてユーザーから明示的な承認を得ていない限り、ルールセット （require_code_owner_review または必須レビュアーのルール）を変更しないでください。
• すでに設定済みのリポジトリでこのスキルを再実行する場合は、ユーザーが変更を依頼した箇所以外は何も変更しないでください。編集を提案する前に、現在のファイルとルールセットの状態を再確認してください。

このスキルの対象外

• ブランチルールセット全般（マージキュー、必須ステータスチェック、PR のレビュー数）— /gh-bootstrap を使用してください。
• コミュニティ向けの健全性ファイル（README、LICENSE、CODE_OF_CONDUCT、CONTRIBUTING、SECURITY、issue および PR のテンプレート）— /oss-hygiene を使用してください。
• 所有権の根拠を収集することに関係しない、ローカルの git 操作。