gh-repospec の使い方Using gh-repospec

前提Prerequisites

GitHub.com に対して gh auth status が成功すること。適用先の管理権限も必要です。gh auth status succeeds for GitHub.com. You also need administrator access to the target repository.

設定のポイントConfiguration

まず実際の設定を YAML に出力します。値を加えたり取り除いたりする前に、対象と管理範囲を確認してください。Export the live settings to YAML first. Review the target and management scope before adding or removing declarations.

設定例Configuration example

# Edit these values in the repository block from import
repository:
  owner: OWNER
  name: REPOSITORY
  topics:
    - platform-team

import が出力した YAML の既存 repository セクション内で、owner・name・topics を編集します。同じキーを別の repository セクションとして重ねて追加しないでください。Edit owner, name, and topics inside the existing repository section exported by import. Do not add a second repository section with duplicate keys.

gh auth status
gh extension install kkamegawa/gh-repospec
gh repospec import OWNER/REPOSITORY --format yaml > repospec.yaml

# Preview the declared changes before applying them
gh repospec validate --file repospec.yaml
gh repospec plan --file repospec.yaml
gh repospec apply --file repospec.yaml

# Confirm that the configuration now converges
gh repospec plan --file repospec.yaml

gh auth status
gh extension install kkamegawa/gh-repospec
gh repospec import OWNER/REPOSITORY --format yaml | Set-Content -Encoding utf8 repospec.yaml

# Preview the declared changes before applying them
gh repospec validate --file repospec.yaml
gh repospec plan --file repospec.yaml
gh repospec apply --file repospec.yaml

# Confirm that the configuration now converges
gh repospec plan --file repospec.yaml

確認方法Check validate が成功し、plan に対象リポジトリと予定する変更が表示されることを確認します。適用後はもう一度 plan を実行します。Confirm that validate succeeds and plan names the target and intended changes. Run plan again after applying.

plan は読み取り専用です。apply は再計画したうえで確認を求めます。設定が宣言していないリソースは削除しません。plan is read-only. apply recalculates the plan and asks for confirmation. Undeclared resources are not deleted.

前提Prerequisites

GitHub CLI で認証し、所有者の下にリポジトリを作成できること。テンプレートリポジトリへのアクセスも確認してください。Authenticate GitHub CLI with permission to create repositories under the owner. Check that you can access the template repository.

設定のポイントConfiguration

下の最小 YAML の YOUR-OWNER、YOUR-REPOSITORY、テンプレートの所有者・名前を実値に置き換えます。さらに設定が必要なら公式の完全な例を参照してください。Replace YOUR-OWNER, YOUR-REPOSITORY, and the template owner and name in this minimal YAML. See the complete official example when you need more settings.

設定例Configuration example

schemaVersion: 1
repository:
  owner: YOUR-OWNER
  name: YOUR-REPOSITORY
  create: true
  visibility: private
seed:
  template:
    repository: YOUR-OWNER/YOUR-TEMPLATE-REPOSITORY

上の YAML を repospec.yaml として保存し、所有者・リポジトリ名・テンプレートを編集します。その後、検証、差分確認、適用を行います。Save the YAML above as repospec.yaml and edit the owner, repository name, and template. Then validate, review the plan, and apply.

cat > repospec.yaml <<'YAML'
schemaVersion: 1
repository:
  owner: YOUR-OWNER
  name: YOUR-REPOSITORY
  create: true
  visibility: private
seed:
  template:
    repository: YOUR-OWNER/YOUR-TEMPLATE-REPOSITORY
YAML
# Replace the placeholder values in repospec.yaml
gh repospec validate --file repospec.yaml
gh repospec plan --file repospec.yaml
gh repospec apply --file repospec.yaml

@'
schemaVersion: 1
repository:
  owner: YOUR-OWNER
  name: YOUR-REPOSITORY
  create: true
  visibility: private
seed:
  template:
    repository: YOUR-OWNER/YOUR-TEMPLATE-REPOSITORY
'@ | Set-Content -Encoding utf8 repospec.yaml
# Edit the placeholder values in repospec.yaml
gh repospec validate --file repospec.yaml
gh repospec plan --file repospec.yaml
gh repospec apply --file repospec.yaml

確認方法Check plan で新規作成の対象、可視性、seed の出所を確認し、承認してから apply を進めます。作成後に plan を再実行して収束を確認します。Use plan to verify the new repository, visibility, and seed source. Review it before approving apply, then run plan again to check convergence.

Free、Pro、Team の GitHub.com リポジトリが対象です。公開／非公開の変更を意図する場合は内容を確認し、既存リポジトリでは allowVisibilityChange: true が必要です。The supported targets are GitHub.com repositories on Free, Pro, and Team. Review visibility carefully; changing an existing repository requires allowVisibilityChange: true.

前提Prerequisites

新しい対象リポジトリと設定元の両方について、適切な権限があること。Actions のシークレットを使う場合は各実行環境で環境変数を設定します。Have the appropriate permissions on both the source and destination repositories. Provide environment variables for any Actions secrets used by the configuration.

設定のポイントConfiguration

repository.owner と repository.name、公開範囲、seed、対象に存在する actor を確認します。宣言されていない項目は管理されません。Check repository.owner, repository.name, visibility, seed, and actors that exist for the target. Undeclared settings are not managed.

設定例Configuration example

# Change the imported file to target another repository
repository:
  owner: OTHER-OWNER
  name: TARGET-REPOSITORY

cp repospec.yaml repospec-target.yaml
# Edit repository.owner, repository.name, and target-specific settings
gh repospec validate --file repospec-target.yaml
gh repospec plan --file repospec-target.yaml

# Apply only after reviewing blocked and changed entries
gh repospec apply --file repospec-target.yaml
gh repospec plan --file repospec-target.yaml

Copy-Item repospec.yaml repospec-target.yaml
# Edit repository.owner, repository.name, and target-specific settings
gh repospec validate --file repospec-target.yaml
gh repospec plan --file repospec-target.yaml

# Apply only after reviewing blocked and changed entries
gh repospec apply --file repospec-target.yaml
gh repospec plan --file repospec-target.yaml

確認方法Check 適用先、blocked/manual の項目、seed の競合、変更される設定を plan で確かめます。完了後に再度 plan を実行します。Use plan to confirm the target, blocked or manual entries, seed conflicts, and settings that will change. Run it again after applying.

同じ構成でも、公開範囲、作成時期、GitHub プランで許可される設定は異なる場合があります。secrets の値は import できず、sourceEnv が示す環境変数から読み込みます。The same configuration can behave differently across visibility, creation date, and GitHub plans. Secrets cannot be imported; values come from environment variables named by sourceEnv.

前提Prerequisites

設定ファイルが保存されているリポジトリで Actions を有効にします。対象が別リポジトリなら、その対象に必要な管理権限を持つ fine-grained PAT または GitHub App installation token を用意します。Enable Actions in the repository that stores the configuration. For a different target, provide a fine-grained PAT or GitHub App installation token with the required administration permissions.

設定のポイントConfiguration

完成した設定を .github/gh-repospec.yaml に保存します。apply は main への設定変更時に実行し、同じ対象への同時適用を直列化します。別の定期 workflow では plan --ci で差分を検出します。Save the complete configuration as .github/gh-repospec.yaml. Run apply when it changes on main and serialize runs for the same target. Use a separate scheduled workflow with plan --ci for drift detection.

設定例Configuration example

# Secret values stay outside this YAML.
actions:
  secrets:
    - name: EXAMPLE_TOKEN
      sourceEnv: EXAMPLE_TOKEN
      updatePolicy: createOnly

保存先: .github/workflows/gh-repospec-apply.ymlSave as .github/workflows/gh-repospec-apply.yml

name: Apply repository specification
on:
  push:
    branches: [main]
    paths: [.github/gh-repospec.yaml]
permissions:
  contents: read
concurrency:
  group: gh-repospec-apply
  cancel-in-progress: false
jobs:
  apply:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Install gh-repospec
        run: gh extension install kkamegawa/gh-repospec
        env:
          GH_TOKEN: ${{ secrets.REPOSPEC_TOKEN }}
      - name: Apply
        run: gh repospec apply --file .github/gh-repospec.yaml --yes
        env:
          GH_TOKEN: ${{ secrets.REPOSPEC_TOKEN }}
          EXAMPLE_TOKEN: ${{ secrets.EXAMPLE_TOKEN }}

同一リポジトリを対象にする場合も、Settings → Secrets and variables → Actions で fine-grained PAT を REPOSPEC_TOKEN として登録してください。トークンには少なくとも対象リポジトリの Administration: write が必要です。seed を書き込む設定には Contents: write、Actions の変数や secrets を管理する設定には追加の Actions 権限も必要です。別のリポジトリを対象にする場合も、その対象に必要な権限を付与します。GitHub App を使う場合は実行ごとに短命の installation token を生成し、各 step の GH_TOKEN に渡します。Create the REPOSPEC_TOKEN secret from a fine-grained PAT under Settings → Secrets and variables → Actions, even for the same repository. The token needs at least Administration: write on the target. Configurations that write seed files need Contents: write; settings for Actions secrets or variables may require additional Actions permissions. Grant the same permissions on any other target repository. If using a GitHub App instead, generate a short-lived installation token for each run and pass it as GH_TOKEN to each step.

YAML の sourceEnv が EXAMPLE_TOKEN なら、その名前の環境変数を workflow に渡します。この例では Secrets の EXAMPLE_TOKEN を適用と差分検出の両方に渡します。When the YAML names EXAMPLE_TOKEN in sourceEnv, pass that environment variable to the workflow. These examples map the EXAMPLE_TOKEN secret to both apply and drift-check steps.

保存先: .github/workflows/gh-repospec-drift.ymlSave as .github/workflows/gh-repospec-drift.yml

name: Check repository specification drift
on:
  schedule:
    - cron: '17 3 * * 1'
  workflow_dispatch:
permissions:
  contents: read
jobs:
  drift:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Install gh-repospec
        run: gh extension install kkamegawa/gh-repospec
        env:
          GH_TOKEN: ${{ secrets.REPOSPEC_TOKEN }}
      - name: Check for drift
        run: gh repospec plan --file .github/gh-repospec.yaml --ci
        env:
          GH_TOKEN: ${{ secrets.REPOSPEC_TOKEN }}
          EXAMPLE_TOKEN: ${{ secrets.EXAMPLE_TOKEN }}

# Run the scheduled check locally
gh repospec plan --file .github/gh-repospec.yaml --ci
# Exit 0: no blocked entries or convergable drift
# Exit 2: convergable drift was found
# Exit 1: command failed or the plan is blocked

# Run the scheduled check locally
gh repospec plan --file .github/gh-repospec.yaml --ci
# Exit 0: no blocked entries or convergable drift
# Exit 2: convergable drift was found
# Exit 1: command failed or the plan is blocked

確認方法Check 適用 job は GitHub Actions のログと、実行後の再計画で確認します。定期チェックでは exit code 2 を差分として扱い、1 は失敗または blocked として調査します。Check the apply job logs and the post-apply plan. Treat exit code 2 as drift and 1 as a failure or blocked plan that needs investigation.

GITHUB_TOKEN は原則としてその workflow のリポジトリ向けです。別リポジトリ用 token は Secrets で管理します。--yes を使っても設定済みコマンドごとの --approve-command <id> は省略できません。定期適用で --force-secrets を使わないでください。GITHUB_TOKEN is generally limited to the workflow repository. Store a separate cross-repository token in Secrets. --yes does not replace per-command --approve-command <id>. Do not use --force-secrets in a scheduled apply.