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.

1. Sync to the origin default branch first

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.

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

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.

3. Compute the next version

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.

4. Create the tag, matching convention

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:

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

5. Push, then watch the release to green

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.

6. Report

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

tag-release

NPX Install

Tags

SKILL.md Content