labels-as-code

labels-as-code

単一の GitHub リポジトリのラベルをバージョン管理下に置き、プルリクエストのラベル付けを変更されたファイルと同期します。

このスキルの用途

対象	スキル
1 つのリポジトリのラベルセットをファイルで管理し、オンデマンドまたはスケジュールに従って同期する	/labels-as-code（このスキル）
1 つのリポジトリでパスに基づいて PR に自動ラベルを付ける	/labels-as-code（このスキル）
複数のリポジトリにまたがるラベルポリシーを、1 つの管理リポジトリから調整する	/safe-settings
イシューフォーム、PR テンプレート、コミュニティ健全性ファイル	/oss-hygiene

/safe-settings は labels ブロックを使って組織全体のラベルも管理でき（oldname による名前変更、除外パターンに対応）、full-sync の実行ごとに調整されます。中央管理リポジトリから複数のリポジトリ間でラベルポリシーを同期させる必要がある場合は、/safe-settings を使用してください。対象が 1 つのリポジトリで、ファイルもそのリポジトリ内にある場合は、このスキルを使用してください。

設定するもの

ファイル	目的
.github/labels.yml	ラベルセット：各ラベルの name、color、description
.github/labeler.yml	actions/labeler が使用するパスとラベルのルール
.github/workflows/labels-sync.yml（任意）	.github/labels.yml をリポジトリに定期同期またはプッシュ時に同期
.github/workflows/labeler.yml（任意）	すべてのプルリクエストで actions/labeler を実行

手順

1. 現在のラベルをエクスポートして差分を確認する

gh label list --json name,color,description

エクスポート結果を、提案する .github/labels.yml と比較します（ファイルがまだ存在しない場合は、assets/labels.yml から作成してください）。変更を提案する前に、作成するラベル、色または説明を変更するラベル、GitHub には存在するがファイルにはないラベルを一覧にした差分を表示してください。

2. デフォルトのラベルセットを提案する

assets/labels.yml には、プレフィックスごとにグループ化された初期ラベルセットが用意されています。

• type/* — /pr-title-lint が PR タイトルでチェックする Conventional Commits のタイプ（feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert）ごとに 1 つのラベルを用意します。
• priority/* — critical、high、medium、low。
• status/* — blocked、in-progress、needs-review。
• good first issue、help wanted — GitHub 独自のコミュニティ標準ラベルです。
• dependencies — Dependabot と手動で行う依存関係更新の PR 用です。
• breaking — 破壊的変更を示すラベルで、リリース時に明記します。

完全な表と、type/* および breaking が /gh-bootstrap の .github/release.yml カテゴリにどのように対応するかについては、references/label-scheme.md を参照してください（このファイルの Breaking changes バケットは breaking-change／breaking をキーにし、Features／Fixes／Documentation／Internal バケットは type/ プレフィックスのない Conventional Commits 形式の名前をキーにします）。リポジトリですでに /gh-bootstrap のリリースノートを使用している場合は、対象の PR で両方のラベル表記を維持するか、release.yml のカテゴリリストに type/* の名前を追加してください。release.yml は /gh-bootstrap が管理するファイルであり、このスキルでは対応関係のみを説明します。

デフォルトのセットをそのまま採用するか、絞り込むか、エクスポートしたラベルを元に始めるかをユーザーに尋ねてください。決めつけないでください。既存のラベルセットが定着しているリポジトリでは、独自の名前を維持したい場合があります。

3. 同期方法

.github/labels.yml をリポジトリに適用する方法は 2 つあります。どちらを実行するか、先にユーザーに尋ねてください。

この手順と手順 4 のワークフローテンプレートでは、Node 24 のアクションを固定しています。どちらかのワークフローをコピーする前に、セルフホストランナーが Actions Runner v2.327.1 以降であることを確認してください。GitHub ホストランナーはすでにこの要件を満たしています。

1 回限りの同期

# Create or update one label (never deletes):
gh label create "<name>" --color "<hex>" --description "<text>" --force

# Clone another repo's full label set (adds only; existing labels keep
# their color/description unless the label doesn't exist yet):
gh label clone <owner>/<repo>

--force は既存ラベルの色や説明を上書きしますが、ソースに存在しないラベルは削除しません。ユーザーからラベルごとの明示的な許可を得ずに、ラベルを削除してはいけません — 削除対象のラベルを一覧表示し、gh label delete を実行する前に承認を待ってください。

定期同期ワークフロー

人手で gh label create を実行せずにドリフトを修正するには、assets/labels-sync.yml を .github/workflows/labels-sync.yml にコピーします。このワークフローは、このスキルで検証済みのメンテナンスされているアクション crazy-max/ghaction-github-labeler を実行します（検証コマンドと現在ピン留めされている SHA については、references/label-scheme.md を参照してください）。テンプレートには skip-delete: true が設定されているため、.github/labels.yml にないラベルは削除されず、そのまま残ります。skip-delete を false に変更するのは、ユーザーが削除を明示的に許可した後に限ってください。手順 1 の差分で、削除されるラベルを正確に確認できます。テンプレートは schedule トリガーによる毎週の実行、.github/labels.yml またはワークフローファイル自体を変更する main への各プッシュ、および手動の workflow_dispatch で実行されます。

EndBug/label-sync も、同じ形式（YAML ファイルから同期し、オプションで制御してデフォルトでは削除）を持つ有効な代替手段です。どちらのアクションもピン留めする前に、gh api repos/{owner}/{repo} と references/label-scheme.md のタグからコミットへの参照を使って、最新リリースと SHA を検証してください。このスキルに記載されている SHA を、現在のリリースと照合せずに再利用しないでください。

4. パスに基づく PR ラベル付け

assets/labeler.yml を .github/labeler.yml にコピーし、リポジトリのディレクトリ構成に合わせてパスの glob を調整します。配布されているファイルは例であり、どのリポジトリにもそのまま適合する設定ではありません。assets/pr-labeler.yml を .github/workflows/labeler.yml にコピーします。このワークフローは、変更されたファイルの読み取りとラベルの書き込みに必要な最小限の権限である permissions: contents: read, pull-requests: write を指定して actions/labeler を実行します。

使用する前に、ピン留めされている SHA を検証してください。

LATEST=$(gh api repos/actions/labeler/releases/latest --jq '.tag_name')
gh api repos/actions/labeler/git/ref/tags/"$LATEST" --jq '.object.sha'

返された SHA が assets/pr-labeler.yml のコメントと一致しない場合は、uses: 行と末尾のバージョンコメントを両方とも一緒に更新してください。新しい SHA の横に古いコメントがあるより、コメントがないほうがましです。

5. 検証

gh label list --json name,color,description

出力が .github/labels.yml と完全に一致すること（名前、色、説明が同じであること。ユーザーが管理対象外のまま残すことを選んだラベルは除きます）を確認してください。次に、.github/labeler.yml のパス条件に一致するパスに触れるプルリクエストを作成し、labeler.yml の実行を監視するか、次のコマンドを使って、想定したラベルが付与されることを確認してください。

gh pr view <number> --json labels --jq '.labels[].name'

作成・更新されたものと変更されなかったもの、および（該当する場合）削除にユーザーの許可がまだ必要なラベルを報告してください。

このスキルの対象外

• 多数のリポジトリに適用する組織全体のラベルポリシーの調整 — /safe-settings を使用してください
• イシューフォーム、PR テンプレート、その他のコミュニティ健全性ファイル — /oss-hygiene を使用してください
• ユーザーからラベルごとの明示的な許可を得ずにラベルを削除すること
• ブランチ保護、マージ設定、リリースノート関連の設定 — /gh-bootstrap を使用してください

注意点

• gh label create --force は色や説明については冪等ですが、ラベルは削除しません。削除には別途、明示的な gh label delete の実行が必要です。事前に確認せず、定期的な同期に削除を組み込まないでください。
• crazy-max/ghaction-github-labeler は、YAML ファイルにないラベルを skip-delete: true が設定されていない場合に削除します。ファイルに列挙されていないラベルがあるリポジトリにワークフローを組み込む前に、このフラグを確認してください。
• actions/labeler の sync-labels 入力は、PR がそのパスに触れなくなったときに、パスに基づくラベルを削除します。ユーザーがその動作を望んでいない限り、デフォルトのまま（false）にしてください。これは自動削除の一種です。
• gh label create --color に指定する色は、# を付けない 16 進文字列です。.github/labels.yml も慣例的に actions/labeler の上流エコシステムに合わせて # なしの値を保存しますが、crazy-max/ghaction-github-labeler はどちらの形式も受け付けます。リポジトリ内のファイルでは、どちらか一方の形式に統一してください。
• gh label create --force でラベル名を変更することはできません。新しいラベルが作成されます。名前を変更する場合は gh label edit <old-name> --name <new-name> を使うか、同期ツールの設定形式が対応していれば from_name: を使ってください。