git-release-start

Git リリース開始

概要

バージョンのイテレーション開始時に、メインの開発ブランチからリリースブランチを作成します。基本原則：まずリモートで作成し、その後ローカルに同期すること — git checkout -b release/X origin/master を実行すると、ローカルブランチは origin/release/X ではなく origin/master を追跡するため、後で push/pull が混乱する原因になります。

連携するスキル：git-release-start（イテレーション開始、このスキル）↔ git-release-finish（イテレーション終了、タグ付け＋マージ）。

---

プラットフォーム別 CLI 対応表

プラットフォーム	CLI ツール	リモートでのブランチ作成
GitLab（SaaS／セルフホスト可能）	glab	glab api POST "projects/:fullpath/repository/branches?branch=<NAME>&ref=<BASE>"
GitHub	gh	gh api repos/:owner/:repo/git/refs -f ref=refs/heads/<NAME> -f sha=<BASE_SHA>

規約：以下の <GIT_CLI> は、プラットフォームの CLI ツールを表します。上記から環境に合う行を選ぶか、他のプラットフォームでは同等のコマンドを使用してください。基本的な git 操作（fetch、checkout）はプラットフォームに依存しません。

---

使用する場合／使用しない場合

使用する場合：

• バージョンのイテレーションが始まり、メインブランチから新しいリリースブランチを作成する必要がある場合
• 同じバージョンのリリースブランチを、複数のリポジトリで連携して作成する必要がある場合
• ブランチの追跡先が正しいこと（誤って master/main を指していないこと）を確認する必要がある場合
• 既存のリリースブランチ命名規則に従う必要がある場合

使用しない場合：

• Git 以外のホスティングプラットフォーム

原則：一連の手順を最後まで実行してください。 リポジトリの数にかかわらず、どのフェーズも省略できません。「単にブランチを作るだけ」という認識が、検証を省略して追跡先を誤る最も一般的な原因です。

前提条件

• 対応するプラットフォームの CLI がインストールされ、認証済みであること
• バージョン番号が確定していること（例：8.2.70）
• ベースブランチが確定していること（例：master または main）

---

フェーズ一覧

フェーズ	操作	主なツール
1	バージョン番号とベースブランチを確認する	—
2	各リポジトリのリリースブランチ命名規則を分析する	git branch -r
3	リモートにリリースブランチを作成する	<GIT_CLI> api
3.5	リリース保護を読み取り、ユーザーの承認後にのみ書き込む	インストールされている場合は git-branch-protect
4	ローカルに同期して追跡先を設定する	git fetch + git checkout --track
5	環境ファイルを更新する	echo／テキスト書き込み
6	検証する	git branch + cat
7	レポートを出力する	—

---

フェーズ 1：バージョン番号とベースブランチの確認

⚠️ 間違ったバージョンで作成したり、誤ったブランチをベースにしたりしないよう、作成前に確認してください。

1.1 バージョン番号の確認

ユーザーのメッセージにバージョン番号がすでに記載されている場合は、再度尋ねずにその番号を使用してください。それ以外の場合は、ユーザーに以下を確認してください。

• 新しいバージョン番号（例：8.2.70）
• 以前のバージョン番号（フェーズ 2 で過去のブランチ命名との比較に使用します。例：8.2.60）

確認項目：

• 新しいバージョンのタグがすでに存在するか：git ls-remote origin refs/tags/<TAG_PATTERN>
• 新しいバージョンのリリースブランチがすでに存在するか：git ls-remote origin refs/heads/release/<VERSION>
• すでに存在する場合はエラーで中止し、再利用するか名前を変更するかをユーザーに確認する

1.2 ベースブランチの確認

リリースブランチはどのブランチから作成しますか？通常はメインの開発ブランチです。

# Confirm the base branch exists and is up to date
git fetch origin <BASE_BRANCH>
git log --oneline origin/<BASE_BRANCH> -3

⚠️ リモートの HEAD が非推奨のブランチを指している場合があります：リポジトリの移行後やブランチポリシーの変更後も、リモートの HEAD が古いメインブランチ（例：master）を指したまま、実際に有効なメインブランチが main に変わっていることがあります。リモートの HEAD が指すブランチが別の候補ブランチより数百コミット遅れている場合、HEAD は古いものです。マージ履歴（git log --merges | grep "into 'main'"）を信頼できる情報源とし、必要に応じてユーザーに確認してください。

出力：確認テーブル（フェーズ 1 ではバージョン番号とベースブランチのみを確認し、リリースブランチ名はフェーズ 2 の分析後に決定します）

Repo	バージョン	ベースブランチ
repo-A	8.2.70	master

確認後、フェーズ 2（リリースブランチの命名規則を分析）に進みます。

---

フェーズ 2：リリースブランチの命名規則を分析

⚠️ リリースブランチの命名規則は、単純に release/X.Y.Z とは限りません。履歴を確認してください。このフェーズでは最終的なブランチ名を出力します。フェーズ 3 でブランチを作成できるのは、このフェーズの完了後です。

# List existing release branches
git branch -r | grep "origin/release"

識別ルール

過去のブランチパターン	命名規則
origin/release/8.2.60、origin/release/8.2.52	release/{VERSION}
origin/release/8.2.60-perf	release/{VERSION}-perf
origin/release/mobile-7.5.720	release/mobile-{VERSION}（製品の接頭辞）

複数製品のリポジトリ：各製品ラインには独自のリリースブランチ命名規則があります。今回は現在の製品ラインのブランチのみを作成してください。

出力：確認テーブル

Repo	リリースブランチ名	過去の例
repo-A	release/8.2.70	release/8.2.60
repo-B	release/8.2.70-perf	release/8.2.60-perf

フェーズ 3 を実行する前に、ブランチ名についてユーザーと合意してください。

---

フェーズ 3：リモートにリリースブランチを作成

⚠️ 重要な教訓：まずリモートに作成してから、ローカルに同期する必要があります。先にローカルで作成してプッシュしてはいけません。

理由：git checkout -b release/X origin/master で作成されたローカルブランチは、origin/release/X ではなく origin/master を追跡するため、後続のプッシュやプルで混乱が生じます。

すべてのリポジトリで並列に実行します。

# GitLab — create the branch on remote via API (`:fullpath` auto-resolves inside the repo directory)
glab api --method POST \
  "projects/:fullpath/repository/branches?branch=<RELEASE_BRANCH>&ref=<BASE_BRANCH>"

# GitHub — `:owner/:repo` auto-resolves when `gh` runs inside the repo directory
BASE_SHA=$(git rev-parse origin/<BASE_BRANCH>)
gh api repos/:owner/:repo/git/refs \
  -f ref="refs/heads/<RELEASE_BRANCH>" \
  -f sha="$BASE_SHA"
# If auto-resolution fails, substitute the actual values manually, e.g.: gh api repos/myorg/myrepo/git/refs ...

パラメーター：

• branch：新しいリリースブランチの完全な名前（パスを含む。例：release/8.2.70）
• ref / sha：作成元のブランチ（メインの開発ブランチ）
• :fullpath：GitLab では自動的に解決されます。GitHub では :owner/:repo を手動で置き換える必要があります

---

フェーズ 3.5：リリース保護を確認

リモートブランチの作成後、利用可能な場合は git-branch-protect を読み込みます。これは glab または gh を使って現在のルールを読み取り、次の 2 つの条件と比較します。一致しない release/* ブランチではプッシュとマージが拒否され、このブランチではプッシュが拒否され、メンテナーによるマージが許可されます。

確認結果	対応
スキルが利用できない	このフェーズをスキップします。保護設定は変更しません
両方の条件をすでに満たしている	結果を記録して続行します
いずれかの条件を満たしていない	現在のルールと目標のルールを提示します。不足している操作ごとに、ユーザーに個別に承認を求めます。ensure-default への「はい」は allow-merge の承認を意味しません。その操作についてユーザーの承認を得てから書き込みを実行します

ユーザーが拒否した場合、ルールは変更せず、リリース作業を続行します。このフェーズでは trunk のルールを書き換えず、set-trunk も実行しません。フェーズ 6 では、保護レポートにこのブランチでプッシュが拒否され、メンテナーによるマージが許可されると記載されている場合、プッシュの拒否を成功として扱います。このレポートは already-met または承認済みの allow-merge の場合があります。

---

フェーズ 4：ローカルに同期して追跡を設定する

⚠️ --track を使用して、ローカルブランチが origin/<RELEASE_BRANCH> を追跡するようにしてください。

すべてのリポジトリに対して並行して実行します：

git fetch origin <RELEASE_BRANCH>
git checkout -b <RELEASE_BRANCH> --track origin/<RELEASE_BRANCH>

追跡を確認します：

git branch -vv | grep '^\*'
# Expected output: * release/8.2.70  <SHA> [origin/release/8.2.70] <commit message>

追跡列に [origin/master] が表示される場合：ブランチの作成方法が誤っています。git branch -u origin/release/8.2.70 で修正してください。

---

フェーズ 5：環境ファイルを更新する

一部のリポジトリでは、現在のブランチ名を release-branch ファイルに記録する必要があります（CI スクリプトなどが読み取る場合があります）。

echo "<RELEASE_BRANCH>" > release-branch
git add release-branch
git commit -m "chore: update release-branch to <RELEASE_BRANCH>"

注：リポジトリが release-branch ファイルを使用していない場合（そのファイルに関する過去のコミットがない場合）は、この手順をスキップしてください。

# Check whether this file has existing history
git log --oneline -- release-branch | head -3

---

フェーズ 6：確認する

各リポジトリで次の確認を実行します：

git push --dry-run origin <RELEASE_BRANCH>
# Pass when the protection report says push is denied and maintainer merge is allowed: the push is rejected
# Pass when that report is absent, or the user declined a write and push is still allowed: the dry-run shows the update, or "Everything up-to-date"
# When the user declined a write and the push is still rejected, record the dry-run and continue. Leave the protection rules unchanged

このプッシュのドライラン以外のチェックに失敗した場合は、停止して修正してください。確認が完了した後に限り、フェーズ 7 に進んでください。 保護レポートで、このブランチはプッシュを拒否し、メンテナーによるマージを許可すると示されている場合、拒否されたドライランは合格です。書き込みが拒否されても、その拒否が失敗に変わることはなく、保護設定の変更が許可されるわけでもありません。

---

フェーズ 7：レポートを出力する

確認用の表を生成します：

リポジトリ	リモートブランチ	ローカルの追跡先	release-branch	状態
repo-A	origin/release/8.2.70	[origin/release/8.2.70]	release/8.2.70	✅
repo-B	origin/release/8.2.70-perf	[origin/release/8.2.70-perf]	N/A	✅

---

エラー処理

状況	対処
タグがすでに存在する	エラーで中止します。リリースが重複している可能性があります
リリースブランチがすでに存在する（リモート）	再利用する（直接チェックアウトする）か、名前を変更するかを確認します
ベースブランチが存在しない	エラーで中止し、正しいベース参照を確認します
glab api が 401 / 403 を返す	glab auth status を確認し、再認証します
追跡先が誤ったブランチ（[origin/master]）を指している	git branch -u origin/<RELEASE_BRANCH> で修正します
同じ名前のローカルブランチがすでに存在する	git branch -D <NAME> でローカルのブランチを削除してから、再度チェックアウトします
push --dry-run が失敗する	リモート URL と権限を確認します

---

よくある間違い

❌ 誤り	✅ 正しい方法	結果
git checkout -b release/X origin/master を実行してからプッシュする	<GIT_CLI> api 経由でリモートに作成 → フェッチ → --track	追跡先が origin/master になり、後のプル／プッシュで混乱が生じます
先にローカルでブランチを作成してから、リモートにプッシュする	先にリモートでブランチを作成してから、ローカルにフェッチする	上記と同じです
フェーズ 5 の release-branch の確認／更新を省略する	確認して更新する	CI が誤った release-branch の値を読み取る可能性があります
すべてのリポジトリで同じ命名規則が使われていると思い込む	リポジトリごとに過去のブランチ名を確認する	一部のリポジトリでは、ブランチ名に特殊な接尾辞（例：-perf）が付いているため、見落とす可能性があります
追跡を確認せずに作業が完了したと判断する	フェーズ 6 の各項目を確認する	追跡先の誤りは、後でマージ／プッシュする際に初めて明らかになります

---

クイックリファレンスコマンド

# List existing release branches
git branch -r | grep "origin/release"

# GitLab — create on remote
glab api --method POST "projects/:fullpath/repository/branches?branch=<NAME>&ref=<BASE>"

# GitHub — create on remote
gh api repos/<OWNER>/<REPO>/git/refs -f ref="refs/heads/<NAME>" -f sha="$(git rev-parse origin/<BASE>)"

# Sync locally
git fetch origin <NAME>
git checkout -b <NAME> --track origin/<NAME>

# Fix tracking (if pointed wrong)
git branch -u origin/<NAME>

# Update release-branch
echo "<NAME>" > release-branch

# Verify
git branch --show-current
git branch -vv | grep '^\*'
git ls-remote origin refs/heads/<NAME>
git push --dry-run origin <NAME>