release

release

バージョン付きリリースを作成します。次のセマンティックバージョンを選び、適切なリリースノートを作成し、コミットにタグを付けて、GitHub リリースを公開します。

このスキルは /gh-bootstrap と並ぶもので、別の問いに答えます。/gh-bootstrap はリリースの 仕組み（.github/release.yml、タグ駆動のワークフロー）を一度設定します。このスキルは、リリースのたびに実行する手順です。バージョンの変更内容を決め、リリースノートを作成し、タグを付けて公開します。この手順以外で単発のリリースコマンドを実行する場合は、gh CLI を直接使用してください。

このスキルの位置づけ

目的	スキル
リリースノート設定とタグ駆動ワークフローの初回設定	/gh-bootstrap
バージョンの決定、リリースノートの作成、タグ付け、公開	/release（このスキル）

リポジトリにタグ駆動のリリースワークフロー（/gh-bootstrap で設定）がある場合は、タグをプッシュするだけでワークフローがリリースを公開します。このスキルでは、引き続きバージョンを決定し、必要に応じて編集したリリースノートを作成します。タグをプッシュした後、gh release create は実行しません。ワークフローの完了を待ってから、承認済みの編集済みリリースノートを適用します。それ以外の場合は、gh release create を使用してリリースを公開します。

手順

1. 事前確認

作業ツリーに変更がある場合、またはブランチが分岐している場合は、リリースを拒否してください。リリースタグは取り消せず、公開されるためです。

git fetch --tags origin
DEFAULT=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)
git diff-index --quiet HEAD || { echo "uncommitted changes — commit or stash first"; exit 1; }
[ "$(git rev-parse HEAD)" = "$(git rev-parse "origin/$DEFAULT")" ] || { echo "HEAD is not the tip of origin/$DEFAULT — check out and update it first"; exit 1; }
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")

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

• タグを付けるコミット。origin/$DEFAULT の先端にあるコミットだけにタグを付けられます。
• 最後のリリースタグ（$LAST_TAG）。バージョンの変更内容とリリースノートの対象範囲を決める基準です。リポジトリにタグがまだない場合は、初回リリースです。

作業ツリーに変更がある場合、または HEAD が origin/$DEFAULT の先端でない場合は、タグを付けずに停止してユーザーに伝えます。

2. バージョンを決める

変更内容を決めるための詳細なルールは references/semver.md を読んでください。要約すると、最後のタグ以降の Conventional Commits を確認し、影響が最も大きい変更に基づいてバージョンの変更内容を決めます。

git log "${LAST_TAG:+$LAST_TAG..}HEAD" --no-merges --pretty='%s'

最後のタグ以降で影響が最も大きい変更	変更内容（≥ 1.0.0）	変更内容（0.x、1.0 より前）
feat!: / fix!: / BREAKING CHANGE: フッター	major	minor
feat:	minor	patch
fix: / perf:	patch	patch
docs / chore / refactor / test / ci のみ	patch（またはスキップ — 確認する）	patch

リポジトリの既存のタグ形式に合わせてください。$LAST_TAG が v1.2.3 なら、次のタグは 1.3.0 ではなく v1.3.0 です。v プレフィックスの有無を確認し、同じ形式を使います。プレリリース識別子（-rc.1、-beta.2）も確認し、ユーザーの慣例に合わせます。

計算したバージョンと、その理由を一行で提示します（「feat が 3 件、破壊的変更なし → minor → v1.3.0」）。ユーザーに確認してもらうか、変更してもらいます。ユーザーが確認していないバージョンにタグを付けてはいけません。

3. リリースノートを作成する

3 つの方法と選び方については references/release-notes.md を読んでください。要約は次のとおりです。

• 自動生成（gh release create --generate-notes）— リポジトリが PR をマージする運用で、.github/release.yml がある場合に最適です。GitHub は、設定済みのカテゴリに基づいて、マージされた PR をラベルごとに分類します。すべての変更がラベル付き PR として取り込まれていれば、手間が最小限で、漏れもありません。
• 手動で編集 — .github/release.yml がない場合、コミット（PR ではなく）が変更の単位となる場合、またはリリースで編集上の注目点を取り上げる必要がある場合に最適です。Conventional Commit の種類ごとに分類し、最初に Highlights セクションを置き、破壊的変更がある場合は具体的な移行手順を記載した Upgrade notes セクションを設けます。基本の構成には assets/release-notes-template.md を使用してください。
• ハイブリッド — 自動生成した後、冒頭を手動で編集して、注目点とアップグレード時の注意事項を追加します。重要なリリースで最もよく選ばれる方法です。

手動で編集する場合は、想像で内容を作らず、コミットログに基づいて項目をまとめます。箇条書きの各項目は、実在するコミットに紐付けられる必要があります。読者が詳細を知りたい箇所には PR やコミットへのリンクを付けます。

4. CHANGELOG.md を更新する（リポジトリで管理している場合）

CHANGELOG.md がある場合は、内容を最新の状態に保ちます。多くのリポジトリは Keep a Changelog に従っています。## [Unreleased] の項目を新しい ## [VERSION] - YYYY-MM-DD 見出しの下に移動し、新しい空の Unreleased を残して、末尾の比較リンクを更新します。変更履歴がなく、ユーザーが作成を希望していない場合は、この手順を省略します。依頼されていない変更履歴を追加しないでください。

タグには変更履歴の項目を含める必要があります。変更履歴の変更をコミットし、リポジトリで通常行われるマージ手順を通じてデフォルトブランチに反映します。明示的なユーザー承認がある場合にのみプッシュしてください。その後、デフォルトブランチの新しい最新コミットで手順 1〜3 をもう一度実施します。スカッシュマージでは新しい SHA が生成されるため、ローカルのコミットではなく、手順 1 で確認した最新コミットにタグを付けます。git log "${LAST_TAG:+$LAST_TAG..}HEAD" の結果と作成したリリースノートを比較します。変更履歴のコミット以外のコミットが反映されていた場合は、作業を中止してユーザーに伝えてください。

5. タグを付けてプッシュする

注釈付きタグを使用します（メッセージ、作成者、日付が記録されます。軽量タグにはこれらがなく、git describe での扱いも異なります）。合意したコミットにタグを付け、そのタグのみをプッシュしてください。

タグ起点のリリースワークフローがある場合（例：.github/workflows/release.yml）、生成されるリリースノートを想定する前に、そのワークフローの gh release create の引数を確認してください。/gh-bootstrap ワークフローが公開するのは生成されたリリースノートのみです（--generate-notes）。ワークフローが生成されたリリースノートを公開し、手順 3 で編集済みまたはハイブリッドのリリースノートを選択した場合は、タグをプッシュする前にユーザーに伝えてください。

タグをプッシュする前に、明示的なユーザー承認を得てください。

VERSION=v1.3.0
git tag -a "$VERSION" -m "$VERSION"        # add -s to GPG-sign if the repo signs tags
git push origin "$VERSION"

タグ起点のリリースワークフローがある場合は、手順 6 を省略します。ワークフローの完了を待ち、承認を得た編集済みリリースノートを gh release edit "$VERSION" --notes-file NOTES.md で適用します。ユーザーの承認がある場合にのみリリースノートを適用してください。ワークフロー実行の URL を報告してください。

6. GitHub リリースを公開する

タグ起点のワークフローがリリースを作成しない場合に限ります。

gh release create を実行する前に、明示的なユーザー承認を得てください。

# Auto-generated notes:
gh release create "$VERSION" --title "$VERSION" --generate-notes --latest

# Curated notes from a file:
gh release create "$VERSION" --title "$VERSION" --notes-file NOTES.md --latest

# Prerelease (rc/beta/alpha) — do NOT mark --latest:
gh release create "$VERSION" --title "$VERSION" --notes-file NOTES.md --prerelease

# Draft for review before going public:
gh release create "$VERSION" --title "$VERSION" --notes-file NOTES.md --draft

プロジェクトがバイナリを配布している場合は、タグの後にビルド成果物を列挙して添付します（gh release create "$VERSION" ... dist/*.tar.gz）。

イミュータブルリリース

GitHub のイミュータブルリリースは、2025-10-28 に一般提供が開始されました。リポジトリで有効にすると、公開済みリリースのアセットとタグは固定され、署名済みの Sigstore アテステーションが付与されます。公開済みのイミュータブルリリースでも、タイトルとリリースノートは編集できますが、アセットの変更やタグの移動はできません。公開前に、添付アセットとタグ付けされたコミットを確認してください。出典については references/release-notes.md を参照してください。

7. 確認して報告する

公開された状態を読み戻して確認してください。作成コマンドの終了コードだけを根拠に成功を報告しないでください。

gh release view "$VERSION" --json tagName,isDraft,isPrerelease,url --jq .
gh release list --json tagName,isLatest --jq '.[] | select(.isLatest) | .tagName'
git ls-remote --tags origin "$VERSION"

ユーザーには、バージョンとその理由、使用したリリースノートの方針、リリース URL、ドラフト／プレリリース／最新のいずれであるかを報告してください。省略したこと（例：「ワークフローが公開処理中のため、リリースはまだ表示されません」）とその理由も明記してください。

このスキルの対象外

• .github/release.yml やリリースワークフローのひな形作成。これは /gh-bootstrap の役割です（最初に一度実行します）。
• リリース手順以外で gh release コマンドのフラグを調べること。gh CLI のリファレンスを直接参照してください。
• リリース手順の開始前に、ブランチのコードをコミットまたはプッシュすること。
• パッケージレジストリ（npm／crates.io／PyPI）への公開。このスキルではタグ付けと GitHub リリースの作成を行います。レジストリへの公開は、プロジェクト独自の just／CI 手順で行います。
• 独立したリリース系列を持つモノレポでのパッケージごとのバージョン管理。対象外です。このスキルでは、1 つのバージョン系列に対して 1 つのタグを作成します。リポジトリが複数パッケージのモノレポである場合は、その旨を伝えてください。

注意点

• 既存のタグの参照先を変更しないでください。 公開済みのタグを移動するために git tag -f と git push -f を実行すると、すでに取得済みのすべての利用者に影響します。誤ったコミットにタグを付けた場合は、新しいパッチバージョンを作成してください。
• 自動生成されるリリースノートに含まれるのは、マージ済みの PR のみです。 デフォルトブランチへの直接プッシュは表示されません。PR ベースのマージを行わないリポジトリ（ブランチ保護がない場合）では、--generate-notes に頼らず、リリースノートを手動で作成してください。
• --generate-notes で適切に分類するには .github/release.yml が必要です。 これがない場合、「変更内容」の一覧が分類されずに表示されます。分類が適切でない場合は、release.yml のカテゴリやラベルを調整してください。ここではなく /gh-bootstrap を使って修正してください。
• プレリリースに --latest を指定しないでください。 -rc ビルドを最新としてマークすると、デフォルトのダウンロード対象となり、releases/latest の参照先になります。--prerelease を指定し、--latest は省略してください。
• 1.0 より前の semver は通常と異なります。 0.x では、破壊的変更の際にメジャーではなくマイナーバージョンを上げます。references/semver.md を参照してください。
• タグはデフォルトブランチの祖先でなければなりません。 フィーチャーブランチのコミットにタグを付けると、レビューされていないコードがリリースされます。タグ付けの前に、そのコミットがデフォルトブランチ上にあること（またはそこにマージされていること）を確認してください。
• 署名付きタグ — リポジトリでリリースに署名している場合（git config tag.gpgSign true またはプロジェクトの慣例）、git tag -s を使用してください。署名付きリリースを採用しているリポジトリで署名なしのタグを使うと、後続の検証に失敗します。