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 或 -R 显式传入该值，避免 GH_REPO、其他远程或已配置的默认值重定向发布操作。
• 从远程的符号 HEAD 解析默认分支，而不是使用本地分支或可能已过时的 origin/HEAD。记录其完整引用名称。
• 不要改动工作树和本地分支。本地检出即使有未提交更改或已分叉，也不影响直接从已获取的远程跟踪引用创建标签。
• 将 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>*'

选择相关的软件包或发布命名空间后，再确定最新版本。仓库可能包含排序结果优先于当前发布系列的无关产品标签、软件包标签或旧格式标签。以远程标签引用为准。即使执行了 git fetch --tags --prune，本地标签也可能已过时或仅存在于本地。确定相关远程系列后，再获取并检查匹配的标签对象。

查看最新发布，了解：

• 版本格式：是否带前导 v、是否有组件或软件包前缀（monorepo 可能使用 pkg-name/v1.2.3 标签），以及是否带预发布或构建后缀。
• 标签类型：轻量标签、附注标签或签名标签。使用 git cat-file -t <tag> 检查（tag 对象表示附注标签或签名标签，commit 表示轻量标签），并使用 git verify-tag <tag> 检查签名。
• 发布机制：发布是否仅需推送标签（由流水线自动处理），还是需要通过 gh release create 显式创建 Forge Release。

如果没有先前的发布，就没有可供升级的版本：使用仓库文档中规定的起始版本，或询问应使用哪个版本。

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、标签类型（轻量／附注／签名），以及发布或流水线的结果。