tag-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tag a release

打发布标签

Tag the current

origin

default-branch HEAD in the repository's established version format and tag kind. Inspect the release convention, compute the next version, verify the exact target, push the tag, and watch the release to green.

The request authorizes creating and pushing the tag and running the repository's established release workflow. Ask only when a required value cannot be derived or the repository state makes the release ambiguous.

按照仓库既定的版本格式和标签类型，标记当前

origin

默认分支的HEAD。检查发布约定，计算下一个版本，验证目标准确性，推送标签并监控发布直至成功完成。

本请求授权创建并推送标签，以及运行仓库既定的发布工作流。仅当无法推导所需值或仓库状态导致发布存在歧义时，才向用户询问。

1. Sync to the origin default branch first

1. 先同步到远程默认分支

The tag must point at what is actually on the remote, not whatever your local checkout happens to be at.

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

Resolve the GitHub
```
owner/repository
```
from the
```
origin
```
URL. Pass that value explicitly with
```
--repo
```
or
```
-R
```
to every
```
gh
```
command so
```
GH_REPO
```
, another remote, or a configured default cannot redirect release operations.
Resolve the default branch from the remote's symbolic
```
HEAD
```
, not from a local branch or a potentially stale
```
origin/HEAD
```
. Record its full ref name.
Leave the working tree and local branches untouched. A dirty or diverged checkout does not affect a tag created directly from the fetched remote-tracking ref.
Record
```
git rev-parse origin/<default-branch>
```
as the candidate release commit. Do not cut a release from a red default branch. If the repository gates releases on CI, verify the checks are green on that exact commit.

标签必须指向远程仓库的实际内容，而非本地检出的任意版本。

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>
```
作为候选发布提交。不要从状态为失败（red）的默认分支发布。如果仓库通过CI管控发布，请验证该特定提交的检查状态为成功（green）。

2. Read the prior release and the repo's convention

2. 读取之前的版本和仓库约定

Never invent a format. Look at what the repo already does:

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

Choose the relevant package or release namespace before selecting the latest version. A repository may contain unrelated product tags, package tags, or legacy formats that sort ahead of the series being released. Treat the remote tag refs as authoritative. Local tags may be stale or local-only even after

git fetch --tags --prune

. Fetch and inspect matching tag objects only after identifying the relevant remote series.

From the latest release, read:

Version format: a leading
```
v
```
or not, any component or package prefix (a monorepo may tag
```
pkg-name/v1.2.3
```
), and any pre-release or build suffix.
Tag kind: lightweight, annotated, or signed. Check with
```
git cat-file -t <tag>
```
(a
```
tag
```
object means annotated/signed, a
```
commit
```
means lightweight) and
```
git verify-tag <tag>
```
for signing.
Release mechanism: whether a release is just a pushed tag (a pipeline picks it up), or an explicit forge Release created with
```
gh release create
```
.

If there is no prior release, there is nothing to bump from: use the repo's documented starting version, or ask which to use.

切勿自行创造格式，遵循仓库已有的做法：

gh release list -R <owner/repository>    # 如果发布是Forge Release对象
git ls-remote --tags --refs origin 'refs/tags/<relevant-prefix>*'

在选择最新版本之前，先选择相关的包或发布命名空间。仓库中可能包含不相关的产品标签、包标签或旧格式，这些可能排在当前发布系列的前面。以远程标签引用为准。即使执行了

git fetch --tags --prune

，本地标签也可能过期或仅存在于本地。只有确定了相关的远程系列后，再获取并检查匹配的标签对象。

从最新版本中读取：

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

如果没有之前的版本，则无需升级：使用仓库文档中指定的起始版本，或询问用户使用哪个版本。

3. Compute the next version

3. 计算下一个版本

Compute a semantic bump from the latest tag in the relevant series, preserving its leading

and any package prefix:

patch:
```
x.y.(z+1)
```
minor:
```
x.(y+1).0
```
major:
```
(x+1).0.0
```

Follow the repository's established transition from prerelease to stable tags. If history does not establish whether to advance, retain, or drop a prerelease suffix, ask the user.

Record the computed tag, candidate commit SHA, tag kind, and release mechanism.

基于相关系列中的最新标签，按照语义化版本规则升级，保留其前置

和任何包前缀：

patch（补丁版）：
```
x.y.(z+1)
```
minor（次版本）：
```
x.(y+1).0
```
major（主版本）：
```
(x+1).0.0
```

遵循仓库已有的从预发布标签到稳定标签的转换规则。如果历史记录无法确定是否要升级、保留或移除预发布后缀，请询问用户。

记录计算出的标签、候选提交SHA、标签类型和发布机制。

4. Create the tag, matching convention

4. 创建符合约定的标签

Immediately before tagging, re-fetch and confirm nothing moved:

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'

The default branch, its SHA, and the latest relevant tag must be unchanged, the proposed tag must not exist, and required checks on the release SHA must be green. If anything moved, recompute the release and repeat this check. If a required check is pending or failing, stop.

Then tag the fetched remote HEAD explicitly, matching the kind of the prior tags:

undefined

在创建标签之前，重新获取并确认远程内容未变动：

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上的必要检查必须为成功状态。如果有任何内容变动，重新计算发布并重复此检查。如果必要检查处于待处理或失败状态，请停止操作。

然后显式标记获取到的远程HEAD，与之前的标签类型保持一致：

undefined

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>"


A global `tag.gpgsign = true` silently turns even a lightweight or annotated tag
into a signed one. If the repo's existing tags are unsigned, pass `--no-sign` so
the new tag matches. If they are signed, sign it.

git tag -a <version> origin/<default-branch> -m "<version>"


全局配置`tag.gpgsign = true`会自动将轻量或附注标签转为签名标签。如果仓库现有标签未签名，请传递`--no-sign`以确保新标签与现有标签一致。如果现有标签已签名，则对新标签进行签名。

5. Push, then watch the release to green

5. 推送标签，然后监控发布直至成功

git push origin <version>

If the convention includes a forge release, create it only after pushing the verified local tag. Use

gh release create <version> --verify-tag ...

, matching how prior releases set their title, notes, and assets, and pass

--repo <owner/repository>

. Then verify the outcome:

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>

For an annotated or signed tag, compare the peeled

^{}

result with the release commit SHA. For a lightweight tag, compare the direct tag result. Do not call it done until the remote tag resolves to the release commit, the release pipeline is green, and the expected release artifacts exist.

git push origin <version>

如果约定包含Forge Release，请在推送已验证的本地标签后再创建它。使用

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. Report

6. 报告

State the version you cut, the commit SHA it points at, how it was tagged (lightweight / annotated / signed), and the release or pipeline result.

说明你创建的版本、标签指向的提交SHA、标签类型（轻量/附注/签名），以及发布或流水线的结果。