gh-bootstrap

gh-bootstrap

マージキュー＋スカッシュマージ＋自動リリースノートのパターンを一度に設定します。

これは /gh（タスクごとの GitHub 操作）と並ぶもので、別の問いに答えます。つまり、このリポジトリはそもそもどのように設定すべきでしょうか？

設定される内容

対象	結果	エンドポイント
リポジトリのマージ設定	スカッシュのみ。PR タイトルをコミットの件名に設定。マージ時にブランチを削除	PATCH /repos/{owner}/{repo}
デフォルトブランチの保護	マージキュー、必須チェック、強制プッシュ禁止、削除禁止を含むルールセット	POST /repos/{owner}/{repo}/rulesets
リリースノート	PR ラベルに基づくカテゴリ分類を含む .github/release.yml	ファイルのコミット
リリースワークフロー（任意）	タグのプッシュ時に、main のみを対象に gh release create --generate-notes を実行	ファイルのコミット

すべてのポリシー関連エンドポイント（リポジトリ設定、ルールセット、ブランチ保護）は gh CLI を介して実行します。JSON エンドポイントには gh api を使用し、専用サブコマンドがある場合は gh repo／gh release を使用します。このスキルはファイル（.github/release.yml、任意のリリースワークフロー）を作業ツリーに直接書き込みます。

手順

1. 対象範囲を確認し、現在の状態を調べる

変更を加える前に、ランウェイを読み、ユーザーに確認します。

gh auth status
gh repo view --json nameWithOwner,visibility,defaultBranchRef,isPrivate
gh api "repos/$REPO" --jq '{
  squash:   .allow_squash_merge,
  merge:    .allow_merge_commit,
  rebase:   .allow_rebase_merge,
  delete:   .delete_branch_on_merge,
  title:    .squash_merge_commit_title,
  body:     .squash_merge_commit_message,
  auto:     .allow_auto_merge
}'
gh api "repos/$REPO/rulesets"                                # any rulesets already?
gh api "repos/$REPO/branches/main/protection" 2>/dev/null    # legacy branch protection?

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

• デフォルトブランチ（リポジトリの defaultBranchRef を前提とし、通常は main）
• 必須ステータスチェックの名前（例：validate / validate skills、ci、test）。CI が出力する名前と一致している必要があります。
• 必須の承認レビュー数（デフォルトは 1。個人用リポジトリなら 0 でもかまいません）
• 任意のリリースワークフローを作成するか、.github/release.yml のみ作成するか

マージキューの利用可否。 GitHub Free でマージキューを利用できるのは、パブリックリポジトリのみです。プライベートリポジトリでは Team または Enterprise が必要です。Free のプライベートリポジトリの場合は、merge_queue ルールをスキップしてユーザーに伝えてください。それ以外の設定は適用され、残りの保護ルールセットもインストールされます。

2. リポジトリのマージ設定を行う

1 回の PATCH ですべてのマージボタン設定をアトミックに適用します。

gh api -X PATCH "repos/$REPO" \
  -F allow_squash_merge=true \
  -F allow_merge_commit=false \
  -F allow_rebase_merge=false \
  -F allow_auto_merge=true \
  -F delete_branch_on_merge=true \
  -F squash_merge_commit_title=PR_TITLE \
  -F squash_merge_commit_message=PR_BODY

各フラグの理由：

• allow_squash_merge=true、allow_merge_commit=false、allow_rebase_merge=false — マージ済み PR のマージ方法をスカッシュのみにすることで、main の履歴をマージ済み PR ごとに 1 つのコミットにします。
• delete_branch_on_merge=true — ブランチは 1 つのコミットにまとめられた時点で不要になるため、参照を残す理由はありません。
• squash_merge_commit_title=PR_TITLE — スカッシュコミットの件名に PR タイトルをそのまま使います。これにより、main で git log --oneline を実行すると、マージ済み PR の一覧として表示されます。
• squash_merge_commit_message=PR_BODY — PR 本文をコミット本文にすることで、GitHub を開かなくても各変更の背景が git log に残ります。
• allow_auto_merge=true — 人が付き添わなくてもマージキューに PR を追加できるようにするために必要です。

PATCH は冪等です。同じ値で再実行しても何も変更されません。

3. ルールセットでデフォルトブランチを保護する

ルールセットは、GitHub におけるブランチ保護の最新の代替機能です。マージキューを第一級のルールとしてサポートし、組織のルールセットとすっきり連携でき、API 経由で照会できます。デフォルトではルールセットを使用し、クラシックなブランチ保護に切り替えるのは、ユーザーが明示的に求めた場合のみとします（たとえば、古いバージョンの GHE に固定されている場合など）。

完全なペイロード、アセットのテンプレート、作成と更新のロジックは references/ruleset.md にあります。この手順の前に、そのファイルを読んでください。標準的な 2 種類のバリアントがアセットとして用意されています。

バリアント	アセット	選択する状況
main: PR + CI	assets/rulesets/main-pr-ci.json	個人または小規模なリポジトリ。allowed_merge_methods: ["squash"] による Squash のみ、必須レビュー 0 件、CI チェック 1 件、マージキューなし。
main-protection（キュー）	references/ruleset.md 内のインライン JSON	PR を並行して処理するチームのリポジトリ。merge_queue ルール、1 件以上のレビュー、複数の CI チェックを追加します。

どちらのバリアントも、共通の構成は次のとおりです。

• target: "branch"、conditions.ref_name.include: ["~DEFAULT_BRANCH"]
• enforcement: "active"
• ルール：deletion、non_fast_forward、pull_request、required_status_checks

ユーザーがマージキューを明示的に求めない限り、main: PR + CI バリアントをデフォルトで使用してください。よりシンプルな構成で、一般的な個人作業にも合っています。

冪等性： 最初にルールセットの一覧を取得し、合意した名前のものを探します。存在する場合は同じ ID に PUT し、存在しない場合は新規作成するために POST します。重複は作成しないでください。

4. リリースノートの設定ファイルを配置する

assets/release.yml を .github/release.yml にコピーします。このファイルは GitHub の自動生成リリースノート（新しいリリースページの「リリースノートを生成」ボタン、および gh release create --generate-notes）で使用されます。PR ラベルに基づいて、マージ済み PR を Breaking／機能／修正／ドキュメント／内部／その他のカテゴリに分類します。

.github/release.yml がすでに存在する場合は、テンプレートとの差分を確認し、上書きする前にユーザーに確認してください。既存のカテゴリを黙って上書きしてはいけません。

5. リリースワークフローを配置する（任意）

ユーザーが有効化を選択した場合は、assets/release-workflow.yml を .github/workflows/release.yml にコピーします。このワークフローは次のとおりです。

• v* タグへの push でトリガーされます
• タグが origin/main の祖先でない場合は公開を拒否するため、レビューされていないブランチからリリースされることはありません
• gh release create "$TAG" --generate-notes を呼び出し、.github/release.yml のカテゴリに基づいて本文を作成します

サプライチェーンの健全性を保つため、Action の SHA は固定されています（変動するタグではありません）。references/release.md には、固定されている Action と、新しいバージョンがリリースされた際の更新方法が記載されています。

6. 検証して報告する

すべてを読み直し、小さな概要テーブルをユーザーに提示します。API から適用後の状態を読み戻さずに、成功したと主張してはいけません。

gh api "repos/$REPO" --jq '{
  squash: .allow_squash_merge, merge: .allow_merge_commit, rebase: .allow_rebase_merge,
  delete: .delete_branch_on_merge, title: .squash_merge_commit_title, body: .squash_merge_commit_message
}'
gh api "repos/$REPO/rulesets" --jq '.[] | {id, name, enforcement, target}'
test -f .github/release.yml          && echo "release.yml present"
test -f .github/workflows/release.yml && echo "release workflow present"

概要では、次の点を取り上げます。

• 変更した内容
• すでに適切だった内容（変更なし）
• スキップした内容（例：無料プランのプライベートリポジトリではマージキューを使用できない場合）とその理由

冪等性のルール

このスキルは、一部だけ設定されたリポジトリでも安全に再実行できるように設計されています。

• リポジトリ設定： PATCH は冪等です。同じ本文を再適用しても、応答上は変更なしとなります。
• ルールセット： 名前で検索し、存在する場合は PUT、存在しない場合は POST します。重複は作成しません。
• .github/release.yml： 上書き前に差分を確認し、内容が異なる場合はユーザーに確認します。
• リリースワークフロー： 同様に、差分を確認してユーザーに確認します。
• 削除しない： 以前の実行で残された成果物（新しいルールセットと併存する旧式のクラシックなブランチ保護ルールなど）がある場合は、ユーザーが判断できるよう提示します。黙って削除してはいけません。

このスキルの対象外

• タスクごとの GitHub 操作（PR、issue、CI ステータス、特定のタグのリリース）には /gh を使用してください
• ローカルの git 操作には /plate を使用してください
• コミット前フックには /prek を使用してください
• プロジェクトのタスク実行には /justfile を使用してください
• CI パイプラインの設計は対象外です。このスキルは依頼された場合に特定のリリースワークフローを 1 つ作成するだけで、それ以上は行いません
• CI がまだ出力していないステータスチェック名をリポジトリに事後追加することは対象外です。使用する名前は提示しますが、CI への組み込みはご自身で行ってください

注意点

• 必須のステータスチェック名は、CI が Checks API に出力する名前と完全に一致している必要があります。PR でチェックが成功した後、gh api repos/$REPO/commits/<sha>/check-runs --jq '.check_runs[].name' を実行して実際の名前を確認してください。気付かれないタイプミスがあると、マージをブロックできません。
• squash_merge_commit_message=PR_BODY に設定したスクワッシュマージでは、PR の説明全体がコミット本文に入ります。整った PR 本文を書くよう促してください。雑な本文は恒久的なコミット履歴になります。
• ルールセットを適用するには、リポジトリの管理者権限が必要です（組織スコープで適用する場合は組織レベルのルールセットが必要です）。push/PR スコープしか持たないトークンでは、ここで 403 が返されます。
• 自動生成されるリリースノートで分類されるのは、マージされた PR のみで、直接コミットは対象外です。デフォルトブランチのルールセットが直接 push をブロックすることで、リリースノートが完全になります。これらの機能は互いに補完し合います。
• マージキューと required_linear_history の組み合わせに問題はありません（スクワッシュでは常に 1 つのコミットが生成されます）が、キューと allow_merge_commit=true の併用は問題があります。リポジトリレベルでマージコミットを無効にしてください。
• このスキルの実行後、PR ビューに「準備ができたらマージ」ボタンが表示されない場合は、allow_auto_merge=true（リポジトリレベル）とルールセットの merge_queue ルールの両方が適用されていることを確認してください。