gh-bootstrap

gh-bootstrap

マージキュー + スカッシュマージ + 自動リリースノートのパターンを実現する、リポジトリの初期設定です。

これはタスクごとの GitHub 操作とは異なる、リポジトリポリシーの一度限りの設定です。つまり、このリポジトリを最初にどのように設定するかを定めます。

設定内容

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

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

手順

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

変更を加える前に、現状を確認してユーザーに確認を取ります。

gh auth status
REPO="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
gh repo view "$REPO" --json nameWithOwner,visibility,defaultBranchRef,isPrivate
DEFAULT_BRANCH="$(gh repo view "$REPO" --json defaultBranchRef --jq '.defaultBranchRef.name')"
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?

# Legacy branch protection: a 404 with "Branch not protected" means none
# exists. Any other error must stop the protocol before rulesets are applied.
if legacy_protection=$(gh api "repos/$REPO/branches/$DEFAULT_BRANCH/protection" 2>&1); then
  echo "$legacy_protection"
elif [[ "$legacy_protection" == *"HTTP 404"* && "$legacy_protection" == *"Branch not protected"* ]]; then
  echo "No legacy branch protection on $DEFAULT_BRANCH."
else
  echo "::error::Could not check legacy branch protection: $legacy_protection" >&2
  exit 1
fi

ユーザーに確認する項目：

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

マージキューの利用条件。 GitHub は、組織所有のパブリックリポジトリ、および GitHub Enterprise Cloud を利用する組織所有のプライベートリポジトリでマージキューをサポートしています。パブリックであっても、ユーザー所有のリポジトリは対象外です。リポジトリとプランが要件を満たしていない場合は、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 にあります。この手順の前に、そのファイルを読んでください。マージキューなしのバリエーションはアセットとして用意されています。

バリエーション	アセット	選択する場面
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 バリエーションをデフォルトで使用してください。よりシンプルな構成で、一般的な個人作業にも適しています。

冪等性： ルールセットを一覧表示し、デフォルトブランチを対象とするもののうち、ブートストラップ用のいずれかのバリエーション名（main: PR + CI または main-protection）に一致するものを探します。見つかった場合は GET で取得し、その rules、bypass_actors、conditions をレンダリング済みペイロードと比較して差分を表示し、PUT する前にユーザーに確認します。ユーザーがバリエーションを切り替える場合は、2 つ目を作成するのではなく、既存ルールセットの ID を再利用して PUT し、以前のバリエーションの無効化や廃止については、ユーザーに事前に確認します。見つからない場合は、新しいものを POST します。デフォルトブランチ用のルールセットを重複して作成してはいけません。

4. リリースノート設定を用意する

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

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

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

ユーザーがオプトインした場合は、assets/release-workflow.yml を .github/workflows/release.yml にコピーします。このワークフローは次の処理を行います。

• v* タグへの push でトリガーされます。
• verify ジョブ（contents: read、persist-credentials: false）を実行します。このジョブでは、リポジトリをチェックアウトし、デフォルトブランチを特定して、タグがその祖先でない場合は処理を中断します。これにより、レビューされていないブランチからリリースされるのを防ぎます。呼び出し元のセットアップと品質ゲートをこのジョブに追加します。
• publish ジョブ（contents: write、needs: verify、チェックアウトなし）を実行し、gh release create "$TAG" --generate-notes --verify-tag を呼び出します。タグに - が含まれる場合は --prerelease を追加します。

verify と publish を分けることで、リポジトリのコードをチェックアウトしてゲートするジョブが contents: write を持たないようにできます。サプライチェーンの衛生管理のため、アクションの SHA は固定されています（可変のタグは使用しません）。新しいバージョンが出たときに、どのアクションが固定されているか、またそれらをどう更新するかは references/release.md に記載されています。

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, reviews: ([.rules[] | select(.type=="pull_request") | .parameters.required_approving_review_count][0])}'
test -f .github/release.yml          && echo "release.yml present"
test -f .github/workflows/release.yml && echo "release workflow present"

サマリーでは、次の点を明記します。

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

冪等性のルール

このスキルは、一部が設定済みのリポジトリに対して安全に再実行できるよう設計されています。

• リポジトリ設定： PATCH は冪等です。同じ本文を再適用すると、何も変更されない応答が返ります。
• ルールセット： デフォルトブランチを対象とする、どちらかのブートストラップバリアント名で検索します。見つかった場合は差分を確認し、PUT の前にユーザーに確認します。バリアントを切り替える際は、既存の ID を再利用します。見つからない場合は POST します。重複は作成しません。
• .github/release.yml： 上書きする前に差分を確認し、内容が異なる場合はユーザーに確認します。
• リリースワークフロー： 同様に、差分を確認してユーザーに確認します。
• 削除は禁止： 以前の実行で成果物（たとえば、新しいルールセットと併存する従来のクラシックなブランチ保護ルール）が残った場合は、ユーザーが判断できるように提示します。黙って削除しないでください。

このスキルの対象外

• タスクごとの GitHub 操作（PR、イシュー、CI の状態、特定のタグのリリース）は対象外です
• ローカルの git 操作は対象外です
• プリコミットフックには /prek を使用してください
• プロジェクトのタスク実行は対象外です
• 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だけで、直接コミットは対象になりません。デフォルトブランチのルールセットが直接プッシュをブロックすることで、リリースノートが完全になります。これらの機能は相互に補完し合います。
• マージキューを使うのは、GitHub で利用資格が確認できた場合に限ってください。ユーザー所有のリポジトリでは、パブリックであってもこのルールを使用できません。リポジトリレベルではマージコミットを無効にしてください。
• このスキルの実行後、PR の画面に「準備ができたらマージ」ボタンが表示されない場合は、allow_auto_merge=true（リポジトリレベル）とルールセットの merge_queue ルールの両方が反映されていることを再確認してください。