safe-settings

safe-settings

github-community-projects/safe-settings を導入します。これは、単一の管理者リポジトリにある YAML ファイルを基に、リポジトリ設定、ブランチ保護、ルールセット、ラベル、チーム、環境、コラボレーターを調整する Probot GitHub App です。

各リポジトリの設定ページをクリックして設定したり、単発の gh api スクリプトを実行したりするのではなく、組織のリポジトリポリシーを大規模に宣言的に管理したい場合に、このスキルを使用します。

safe-settings と代替手段の使い分け

状況	ツール
単一リポジトリで、一度だけポリシーをロックダウンする	/gh-bootstrap（gh CLI、命令型）
多数のリポジトリで、常に同期を保つ必要がある一元的なポリシー、ドリフト検出、PR でのドライラン	safe-settings（このスキル）
タスクごとの GitHub 操作（PR、イシュー、CI ステータス）	このカタログの対象外

ポリシーを複数のリポジトリで共有し、ポリシー変更そのものに対して PR とドライランによるゲートを設けたい場合は、safe-settings が最適な選択肢です。単一のリポジトリには過剰です。

このスキルの実行後に safe-settings で設定される内容

• リポジトリのメタデータ（説明、ホームページ、トピック、公開設定、デフォルトブランチ、機能の切り替え）
• マージボタンの設定（squash／merge／rebase、マージ時の削除、自動マージ、ブランチの更新）
• セキュリティの切り替え（脆弱性アラート、自動セキュリティ修正）
• ブランチ保護（従来型）とルールセット（最新型）
• ラベル（oldname による名前変更、除外パターン）
• マイルストーン
• コラボレーター（ユーザーごと、include／exclude リポジトリリスト指定）
• チーム（権限、公開設定）
• 環境とデプロイルール
• カスタムプロパティ
• 自動リンク（Jira 形式の参照）

同じ YAML スキーマを組織 → サブ組織 → リポジトリの順に階層化し、リポジトリレベルのファイルを優先します。

プロトコル

1. 管理者リポジトリを選び、対象範囲を確認する

safe-settings は、組織内の単一の管理者リポジトリから設定を読み込みます。一般的な構成は次の 2 つです。

管理者リポジトリ	使用する状況
<org>/.github	最も手軽です。組織ですでにコミュニティ向けのヘルスファイル用にこのリポジトリを使用している場合に適しています。ADMIN_REPO=.github を設定します。
<org>/admin（専用）	専任のポリシーチームがリポジトリを管理する大規模な組織に適しています。ADMIN_REPO=admin を設定します。

ユーザーに次の点を確認します。

• 組織名（ユーザーアカウントの場合は gh api user --jq '.login'、組織を確認するには gh api orgs/<org>）
• 管理者リポジトリの選択（一般的なデフォルトは .github）
• サブ組織によるグループ化が必要か（例：異なるポリシーを適用するため、チームごとにリポジトリをグループ化する）
• デプロイ方法はGitHub Actions cron（最も簡単）か、ホスト型 Probot アプリ（リアルタイムの Webhook）か

2. 管理者リポジトリの構成を作成する

管理者リポジトリ内の標準的な構成：

<admin-repo>/
└── .github/
    ├── settings.yml              # org-level baseline — applies to all repos
    ├── suborgs/                  # optional — overrides for groups of repos
    │   └── <suborg-name>.yml
    └── repos/                    # optional — per-repo overrides
        └── <repo-name>.yml

assets/ からコピーするファイル：

• assets/settings.yml → .github/settings.yml — 最小限の、意見を反映した組織のベースライン（以下を参照）
• assets/suborg.yml → .github/suborgs/example.yml — コメント付きのサブ組織テンプレート
• assets/repo.yml → .github/repos/example.yml — コメント付きのリポジトリごとのオーバーライドテンプレート

assets/settings.yml の組織ベースラインは、gh-bootstrap のデフォルト設定を踏襲しています。squash のみのマージ、PR タイトルをコミットメッセージに使用する設定、マージ時のブランチ削除が含まれます。ルールセットは無効な状態で始まります。有効化する前に、対象リポジトリを絞り込み、実際のチェック名を確認し、明示的な承認を得てください。対象の組織とプランが対応している場合に限り、merge_queue ルールを追加してください。キーの一覧と階層化の動作については、references/schema.md を参照してください。

3. デプロイ方法を選択する

GitHub Actions cron（開始時におすすめ）

• セットアップコストが最も低く、ホスティングや Webhook トンネルは不要です
• npm run full-sync により、N 時間ごとに設定を調整します
• ドリフトはリアルタイムではなく、cron の間隔内に修正されます
• assets/full-sync.yml を <admin-repo>/.github/workflows/safe-settings.yml にコピーします

ホスト型 Probot アプリ

• Webhook イベント（.github/settings.yml へのプッシュ、リポジトリの作成など）にリアルタイムで応答します
• ホスティング環境（AWS Lambda、Docker、Heroku、k8s）と、Webhook 用の公開 URL が必要です
• cron の方法が実証され、組織が即時の照合を希望する場合に使用します
• デプロイの対応表と環境変数のリファレンスについては、references/deploy.md を参照してください

このスキルでは、デフォルトで GHA cron の方法を使用します。ユーザーから依頼があった場合にのみ、ホスト型に切り替えてください。

4. GitHub App を作成する

どちらのデプロイ方法でも、GitHub App のインストールが必要です。マニフェストの手順をユーザーに案内してください。

1. safe-settings をローカルにクローンします：git clone https://github.com/github-community-projects/safe-settings
2. cd safe-settings
3. cp .env.example .env を実行し、GH_ORG=<org> を設定します
4. npm install && npm run dev
5. 表示された URL を開き、［Register a GitHub App］を選択して、組織にインストールします
6. 次の値を保存します：
   • App ID → vars.SAFE_SETTINGS_APP_ID（リポジトリまたは組織の変数）
   • Private key（ダウンロードした .pem）→ secrets.SAFE_SETTINGS_PRIVATE_KEY（ファイルの内容を貼り付けます）
   • Client ID → vars.SAFE_SETTINGS_GITHUB_CLIENT_ID
   • Client secret → secrets.SAFE_SETTINGS_GITHUB_CLIENT_SECRET
   • Webhook secret → secrets.SAFE_SETTINGS_WEBHOOK_SECRET（ホスト型 Probot でのみ必要です）

GitHub App には、設定を管理するための組織のリポジトリへの管理者アクセス権が必要です。マニフェストの手順では適切な権限が自動的に要求されるため、権限の一覧を手動で作成しないでください。

5. 接続してテストする

GHA の方法の場合：

# Set the variables and secrets on the admin repo (or org-wide).
gh variable set SAFE_SETTINGS_GH_ORG --body "<org>" --repo "<org>/<admin-repo>"
gh variable set SAFE_SETTINGS_APP_ID --body "<app-id>" --repo "<org>/<admin-repo>"
gh variable set SAFE_SETTINGS_GITHUB_CLIENT_ID --body "<client-id>" --repo "<org>/<admin-repo>"
gh secret set SAFE_SETTINGS_PRIVATE_KEY --repo "<org>/<admin-repo>" < private-key.pem
gh secret set SAFE_SETTINGS_GITHUB_CLIENT_SECRET --repo "<org>/<admin-repo>"

workflow_dispatch を使って、最初の同期を手動で実行します：

gh workflow run safe-settings.yml --repo "<org>/<admin-repo>"
gh run watch --repo "<org>/<admin-repo>"

実行結果を確認します。最初の full-sync でリポジトリがすぐに照合され、適用された変更がログに記録されます。この最初の実行の前に、対象となる組織と設定のスコープを確認してください。

6. ガードレールを検証する

safe-settings は 2 つの安全策を提供できますが、デプロイ時に接続する必要があります。

• ホスト型アプリの PR ドライラン — ホスト型 Probot の Webhook 経路では、設定変更に対するステータスチェックを投稿できます。デフォルトの cron および workflow_dispatch ワークフローには、この PR ガードレールはありません。ホスト型の方法が設定されていない場合は、利用できないものとして報告してください。
• バリデーター — assets/settings.yml には、リポジトリ名に対する validator.pattern が含まれています。名前が不適切なリポジトリに validation-error トピックを追加するだけで、設定の照合をブロックするものではありません。リポジトリを同期対象から除外するには、デプロイの restrictedRepos 設定を構成してください。

より厳格な設定にするには、新しいルールセットに enforcement: evaluate を追加し、active に切り替える前にシャドウモードでテストしてください。references/schema.md を参照してください。

冪等性

safe-settings は照合を中心に設計されており、変更されていない設定に対して full-sync を実行しても何も変更されません。このスキル自体も冪等です。

• ファイルのひな形作成：assets/ のテンプレートと差分を比較し、既存のファイルを上書きする前に確認します
• 変数／シークレット：gh variable set と gh secret set は冪等です（最後の書き込みが優先されます）。このスキルでは、既存の値を上書きする前に確認する必要があります
• GHA ワークフローファイル：同様に、差分を比較して確認します

一部だけ設定済みの管理者リポジトリでスキルを再実行すると、不足している部分だけが補われます。

このスキルの対象外

• 組織に属していない単一のリポジトリに、一度限りのポリシーを設定すること — /gh-bootstrap を使用してください
• PR／issue／CI の運用や、ローカルの git 作業 — このカタログの対象外です
• safe-settings の新しいルールを上流で作成すること — このスキルはリリース済みのアプリを利用するものであり、開発するものではありません
• 以前の github/settings アプリから移行すること — safe-settings はサポート対象の後継アプリです。このスキルでは、新規に開始するか、すでに github/settings を使用していないことを前提としています

注意点

• 管理者リポジトリのパスは重要です。デフォルトでは、safe-settings は ADMIN_REPO 内の .github/ の下で設定を探します。別の場所に置く場合は、CONFIG_PATH にそのディレクトリを設定してください。
• GitHub App には、メンバーリポジトリの設定を管理するための admin アクセス権が必要です。ユーザーがインストールしたトークンでは不十分です。組織にインストールされた App である必要があります。
• GHA 経由の full-sync は、実行のたびに App がインストールされているすべてのリポジトリを確認します。サブ組織のファイルはリポジトリごとに適用するオーバーライドを選ぶだけで、確認対象のリポジトリを絞り込みません。大規模な組織（リポジトリが 1000 個超）の場合、実行に 1 時間かかり、Actions の実行時間を消費することがあります。デプロイの restrictedRepos 設定を行うか、App のインストール先を減らして負荷を抑えてください。
• 同じ YAML キーでも、階層によって意味が異なることがあります。組織レベルの branches はすべてのリポジトリに適用され、リポジトリレベルの branches はそのリポジトリだけをオーバーライドします。マージの順序は深い階層まで適用されるため、複雑なオーバーライドを記述する前に references/schema.md を確認してください。
• 組織レベルの settings.yml アセットでは、ルールセットが無効になっており、狭い repository_name.include: ["example-repo"] プレースホルダーが設定されています。実際に確認した限定的なセレクターに置き換え、適用前に明示的な承認を得てください。有効な組織ルールセットを、より低いスコープのファイルで弱めることはできません。
• settings.yml では labels ブロックがコメントアウトされています。これを有効にして full-sync を実行すると、リストにないすべてのラベルが組織全体から削除されます。有効にする前に、組織内の既存ラベルをすべて確認し、include/exclude リストについてオペレーターの承認を得てください。
• 初回の同期前に、管理者リポジトリ自体を保護してください。デフォルトブランチに有効なルールセットを設定し、少なくとも 1 件の必須レビューと、設定パスに対するコードオーナーのレビューを要求してください。また、CODEOWNERS ファイルを用意し、誰が書き込みアクセス権を持つか確認してください。管理者リポジトリは信頼境界です。ここにプッシュできる人は誰でも、App を通じて組織内のすべてのリポジトリを制御できます。
• repos/<name>.yml の force_create: true は、リポジトリが存在しない場合に作成します。強力で危険な設定のため、意図を持って使用してください。
• safe-settings は、すべての API フィールドをデフォルトで解除するわけではありません。labels.exclude は一致するラベルを保持し、削除はしません。コラボレーターを削除するには、通常、エントリを削除して同期を実行します。「YAML から削除する」ことが「GitHub から削除する」ことを意味すると決めつける前に、スキーマを確認してください。
• マージキューは、トップレベルの切り替え項目ではなく、rulesets エントリ内の merge_queue ルールです。/gh-bootstrap のルールセットペイロードと同じ形式で、YAML で記述し、組織全体に適用します。