git-release-start

Git 发布开始

概述

在一个版本迭代开始时，从主开发分支创建发布分支。核心原则：先在远程创建，再同步到本地——git checkout -b release/X origin/master 会让本地分支跟踪 origin/master，而不是 origin/release/X，为之后的推送／拉取混乱埋下隐患。

配对技能：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-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-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/master，而非 origin/release/X，导致后续推送和拉取时产生混淆。

对所有仓库并行运行：

# 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 读取实时规则，并与以下两项条件进行比较：未匹配的 release/* 分支禁止推送且禁止合并；此确切分支禁止推送且允许维护者合并。

读取结果	操作
技能不可用	跳过本阶段。保持保护规则不变
两项条件均已满足	记录报告并继续
有条件未满足	显示实时规则和目标规则。分别询问用户是否接受每项未满足的操作。接受 ensure-default 不代表接受 allow-merge。只有在用户接受相应操作后才能执行写入

用户拒绝时，规则保持不变，发布流程继续。如果保护报告显示此分支禁止推送且允许维护者合并，则阶段 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 在远程创建 → fetch → 使用 --track	跟踪指向 origin/master，导致后续拉取/推送时产生混淆
先在本地创建分支，再推送到远程	先在远程创建分支，再 fetch 到本地	后果同上
跳过阶段 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>