tag-release

リリースにタグを付ける

リポジトリで確立されているバージョン形式とタグの種類に従い、現在の origin のデフォルトブランチの HEAD にタグを付けます。リリース規約を確認して次のバージョンを算出し、対象が正確であることを検証してからタグをプッシュし、リリースが成功するまで監視します。

この依頼では、タグの作成とプッシュ、およびリポジトリで確立されているリリースワークフローの実行が許可されています。必要な値を導き出せない場合、またはリポジトリの状態からリリースが曖昧になる場合に限り、質問してください。

1. まず origin のデフォルトブランチと同期する

タグの対象は、ローカルのチェックアウトの状態ではなく、リモートに実際にあるコミットでなければなりません。

git remote get-url origin
git ls-remote --symref origin HEAD
git fetch origin --tags --prune

• origin の URL から GitHub の owner/repository を特定します。リリース操作が GH_REPO、別のリモート、または設定済みのデフォルトによって別のリポジトリに向けられないよう、すべての gh コマンドにその値を --repo または -R で明示的に指定します。
• ローカルブランチや古くなっている可能性のある origin/HEAD ではなく、リモートのシンボリック HEAD からデフォルトブランチを特定します。完全な ref 名を記録してください。
• 作業ツリーとローカルブランチには手を加えないでください。ダーティなチェックアウトや分岐したチェックアウトでも、取得済みのリモート追跡 ref を直接指定してタグを作成する場合には影響しません。
• git rev-parse origin/<default-branch> の結果をリリース候補コミットとして記録します。デフォルトブランチの CI が失敗している状態からリリースしてはいけません。リポジトリでリリースに CI の通過が必須の場合は、その正確なコミットでチェックが成功していることを確認してください。

2. 直近のリリースとリポジトリの規約を確認する

形式を推測で決めてはいけません。リポジトリの既存の方法を確認してください。

gh release list -R <owner/repository>    # if releases are forge Release objects
git ls-remote --tags --refs origin 'refs/tags/<relevant-prefix>*'

最新バージョンを選ぶ前に、対象のパッケージまたはリリースの名前空間を特定します。リポジトリには、別製品のタグ、パッケージのタグ、または先行して並べ替えられる古い形式のタグが含まれている場合があります。リモートのタグ ref を正として扱います。git fetch --tags --prune の後でも、ローカルのタグが古い場合やローカルにしか存在しない場合があります。対象となるリモートのタグ系列を特定してから、該当するタグオブジェクトを取得して確認してください。

最新のリリースを基に、以下を確認します。

• バージョン形式：先頭に v が付くか、コンポーネント名やパッケージ名のプレフィックスがあるか（モノレポでは pkg-name/v1.2.3 のようなタグを付ける場合があります）、プレリリースやビルドのサフィックスがあるか。
• タグの種類：軽量タグ、注釈付きタグ、署名付きタグのいずれか。git cat-file -t <tag> で確認します（tag オブジェクトなら注釈付きまたは署名付き、commit なら軽量タグです）。署名は git verify-tag <tag> で確認します。
• リリースの仕組み：プッシュしたタグだけでよいか（パイプラインが処理します）、それとも gh release create で明示的にフォージのリリースを作成するか。

過去のリリースがない場合、次のバージョンの基準にできるものはありません。リポジトリで文書化されている開始バージョンを使用するか、どのバージョンを使うべきか質問してください。

3. 次のバージョンを算出する

対象のタグ系列で最新のタグを基に、セマンティックバージョニングに従ってバージョンを更新し、先頭の v とパッケージのプレフィックスを維持します。

• パッチ：x.y.(z+1)
• マイナー：x.(y+1).0
• メジャー：(x+1).0.0

プレリリースタグから安定版タグへの移行は、リポジトリで確立されている方法に従ってください。履歴からサフィックスを進める、維持する、または削除する判断ができない場合は、ユーザーに質問してください。

算出したタグ、候補コミットの SHA、タグの種類、リリースの仕組みを記録します。

4. タグを作成する（一貫性を保つ）

タグ付けの直前に、再取得して何も変わっていないことを確認します。

git ls-remote --symref origin HEAD
git fetch origin --tags --prune
git rev-parse origin/<default-branch>
git ls-remote --tags --refs origin 'refs/tags/<relevant-prefix>*'
gh api 'repos/<owner>/<repository>/commits/<release-sha>/check-runs'
gh api 'repos/<owner>/<repository>/commits/<release-sha>/status'

デフォルトブランチ、その SHA、最新の関連タグに変更がなく、作成予定のタグが存在せず、リリース SHA に対する必須チェックがすべて成功している必要があります。何かが変わっていた場合は、リリースを再計算してこの確認を繰り返します。既存の CI ウォッチャーで保留中のチェックを待ち、その後ターゲットを再確認します。チェックに失敗した場合は、原因を調査し、許可された範囲内でのみ修正します。必須チェックが未解決の間はタグを付けないでください。独立した準備は続け、修正に新たな許可や利用できないアクセスが必要な場合は、ブロッカーとして報告します。

次に、取得したリモート HEAD を明示的に指定し、以前のタグの種類に合わせてタグを付けます。

# lightweight (prior tags are lightweight):
git tag <version> origin/<default-branch>

# annotated (prior tags are annotated):
git tag -a <version> origin/<default-branch> -m "<version>"

グローバルな tag.gpgsign = true の設定があると、軽量タグも注釈付きタグも、警告なしに署名付きタグになります。リポジトリの既存のタグが署名なしの場合は、新しいタグも同じ形式にするため、--no-sign を指定します。既存のタグが署名付きの場合は、署名します。

5. プッシュして、リリースが成功するまで監視する

git push origin <version>

運用上の慣例として Forge リリースを作成する場合は、検証済みのローカルタグをプッシュした後にのみ作成します。以前のリリースでのタイトル、リリースノート、アセットの設定に合わせて gh release create <version> --verify-tag ... を使い、--repo <owner/repository> を指定します。その後、結果を検証します。

git ls-remote origin 'refs/tags/<version>' 'refs/tags/<version>^{}'
gh run watch <run-id> -R <owner/repository> --exit-status --interval 20
gh release view <version> -R <owner/repository>

注釈付きタグまたは署名付きタグの場合は、剥離した ^{} の結果とリリースのコミット SHA を比較します。軽量タグの場合は、タグの直接の結果を比較します。リモートタグがリリースのコミットを指し、リリースパイプラインが成功し、想定されるリリースアーティファクトが存在するまでは、完了としないでください。

6. 報告

リリースしたバージョン、そのタグが指すコミット SHA、タグの種類（軽量／注釈付き／署名付き）、およびリリースまたはパイプラインの結果を伝えます。