safe-settings

safe-settings

github/safe-settings を導入します。これは、1 つの管理用リポジトリにある YAML ファイルから、リポジトリ設定、ブランチ保護、ルールセット、ラベル、チーム、環境、コラボレーターを調整する Probot GitHub アプリです。

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

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

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

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

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

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

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

手順

1. 管理用リポジトリを選び、適用範囲を確認する

safe-settings は、組織内の 1 つの管理用リポジトリから設定を読み込みます。一般的な構成は次の 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 タイトルをコミットメッセージに使用、マージ後の削除に加え、マージキューと必須レビューを設定したデフォルトブランチのルールセットが含まれます。すべてのキーの一覧とレイヤーの仕組みについては、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 への push、リポジトリ作成など）にリアルタイムで応答します。
• ホスティング（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/safe-settings
2. cp .env.example .env を実行し、GH_ORG=<org> を設定します
3. npm install && npm run dev を実行します
4. 表示された URL を開き、「Register a GitHub App」を選択して、組織にインストールします
5. 次の値を保存します：
   • App ID → vars.SAFE_SETTINGS_APP_ID（リポジトリまたは組織の変数）
   • 秘密鍵（ダウンロードした .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 --body "$(cat private-key.pem)" --repo "<org>/<admin-repo>"
gh secret set SAFE_SETTINGS_GITHUB_CLIENT_SECRET --body "<secret>" --repo "<org>/<admin-repo>"

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

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

実行ログを確認します。最初の同期では適用される変更がすべて記録されます。以降の実行では、設定にずれがない限り何も出力されません。

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

safe-settings には 2 つの安全策があります。両方が設定されていることを確認してください。

• PR でのドライラン — 誰かが設定を変更する PR を管理リポジトリに作成すると、アプリは適用される変更を示すステータスチェックを投稿します。チェックに失敗した場合はマージしないでください。
• バリデーター — assets/settings.yml には、リポジトリ名を検証する validator.pattern が含まれています。組織の命名規則に合わせてカスタマイズし、名前が規則に合わないリポジトリには safe-settings が設定を適用しないようにします。

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

冪等性

safe-settings は調整型の仕組みです。設定に変更がない状態で full-sync を実行しても何も起こりません。このスキル自体も冪等です。

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

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

このスキルの対象外

• 組織に属さない単独のリポジトリにポリシーを設定する場合 — /gh-bootstrap を使用します
• PR／Issue／CI の操作 — /gh を使用します
• ローカルでの Git 作業 — /plate を使用します
• safe-settings の新しいルールを上流で作成する場合 — このスキルはリリース済みアプリを使用するものであり、開発するものではありません
• 古い github/settings アプリから移行する場合 — safe-settings はサポート対象の後継アプリです。このスキルは、新規に開始するか、すでに github/settings から移行済みであることを前提とします

注意点

• 管理リポジトリのパスが重要です。デフォルトでは、safe-settings は ADMIN_REPO 内の .github/ に設定ファイルを探します。別の場所に置く場合は、CONFIG_PATH にそのディレクトリを設定してください。
• GitHub App には、メンバーのリポジトリの設定を管理するための admin アクセス権が必要です。ユーザーがインストールしたトークンでは不十分です。組織にインストールされた App である必要があります。
• GHA 経由の full-sync は、実行のたびに組織内のすべてのリポジトリに影響します。巨大な組織（リポジトリ数が 1000 を超える）の場合、実行に 1 時間かかり、Actions の実行時間を大量に消費する可能性があります。ホスト型 Probot の方法を使うか、サブ組織で範囲を絞ってください。
• 同じ YAML キーでも、階層によって意味が異なる場合があります。組織レベルの branches はすべてのリポジトリに適用されますが、リポジトリレベルではそのリポジトリだけを上書きします。マージは階層的に行われます。複雑な上書きを記述する前に、references/schema.md を確認してください。
• 組織レベルの settings.yml を変更すると、次回の同期時にすべてのリポジトリに変更が適用されます。ルールセットで enforcement: evaluate を使う場合を除き、「最初に一部のリポジトリだけに適用する」切り替え方法はありません。
• repos/<name>.yml の force_create: true は、リポジトリが存在しない場合に作成します。強力な機能である一方、危険も伴うため、意図を持って使用してください。
• safe-settings は、デフォルトですべての API フィールドを解除するわけではありません。ラベルを削除するには、labels.exclude に記載する必要があります。コラボレーターを削除するには、通常、その項目を削除して同期を実行します。「YAML から削除する」ことが「GitHub から削除する」ことを意味すると決めつけず、スキーマを確認してください。
• マージキューは、トップレベルの切り替え項目ではなく、rulesets エントリー内の merge_queue ルールです。/gh-bootstrap のルールセットペイロードと同じ形式を YAML で記述し、組織全体に適用します。