Release workflows
Prefer creating the release commit and annotated tag together on the configured release branch. Git-std also supports preparing a release first and tagging it later, for repositories that require release PRs or teams that prefer two steps. Both processes leave the tag pointing to the intended release commit in the release branch’s history.
Before releasing
Read .git-std.toml, repository instructions and hosting rules. Discover the
release branch and its remote; do not assume main and origin. Fetch current
remote state, preserve local work, and require a clean, synchronized release
branch before creating a new release. Stop on divergence rather than discarding
commits or force-pushing. In a worktree, avoid switching a branch owned by another
checkout.
Run git std bump --dry-run with the intended package and version options.
Review the version, changed files and changelog. Confirm unresolved release and
publication decisions; an agent should reuse authorization already given in the
session. Promoting 0.x to 1.0 requires an explicit stability decision and
--first-major-release. A prerequisite error is not permission to bypass policy.
The examples below use main, origin and 1.2.3. Substitute the discovered
branch, remote and exact planned tags. Run the repository’s validation command
on the generated release revision before publishing it. A successful check on
the revision before the bump does not validate the changed release files.
Preferred: create the commit and tag together
Normal development changes arrive through reviewed PRs. Where release commits may be pushed directly, create the bump commit and tag on the release branch:
git switch main
git fetch origin
git merge --ff-only origin/main
git std bump --dry-run
git std bump
just verify
git push --atomic --no-follow-tags --recurse-submodules=no origin \
refs/heads/main:refs/heads/main refs/tags/v1.2.3:refs/tags/v1.2.3
just verify is an example: use the project’s prescribed validation command.
Check synchronization in both directions before bumping; merge --ff-only alone
does not detect local commits ahead of the remote. For multiple package tags,
include each planned tag as an explicit refspec in the same atomic push.
An atomic push prevents a rejected branch update from leaving a published tag whose release commit did not reach main. If the server lacks atomic support, stop and resolve the publication process; do not retry non-atomically. Check that the remote has one identical effective fetch/push URL before using this recipe.
git std bump --push and git push --follow-tags remain supported, but do not
guarantee atomic branch/tag publication. The agent skill uses the explicit atomic
sequence so checks run after the bump and only the selected refs are sent.
Supported alternative: prepare, then tag
Prepare version files, changelog and the release commit without a tag:
git switch -c release/1.2.3 origin/main
git std bump --dry-run --no-tag
git std bump --no-tag --yes
just verify
git push origin HEAD:refs/heads/release/1.2.3
Here --yes acknowledges the deliberate preparation on a non-release branch;
it does not grant hosting-policy exceptions. --no-tag --push skips pushing,
so push the preparation branch explicitly. Open the release PR with the generated
chore(release): 1.2.3 subject as its title. Preserve that identity when merging.
For package releases, preserve the complete generated package/version list.
If the PR is pending, stop with the preparation branch, PR and validation results recorded. When it merges, obtain the resulting release commit ID from the forge and fetch it. Squash and rebase merges can rewrite the original commit; a tag created beforehand does not follow the new commit. Never infer the target solely from the current tip of main or an ambiguous search for a release subject.
Validate the resulting release revision. If main has advanced, use an isolated checkout of the exact release commit for validation. Then:
git fetch origin
git std tag <merged-release-commit> --push origin --dry-run
git std tag <merged-release-commit> --push origin
git std tag reads release identity, versions and tag configuration from that
commit. It creates no new release commit, changes no version or changelog,
and runs no bump lifecycle hooks. With --push, the observed remote release
branch is authoritative; a stale or absent local main does not block a valid
merged release. Only the selected tags are pushed atomically, never the branch.
For local-only tagging, omit --push and ensure the target is reachable from
the local release branch.
Existing-release tagging reference
git std tag <commit> [--dry-run] [--branch <name>]
[--package <name>]... [--sign]
[--push <remote>] [--format text|json]
<commit>is required and pinned to its full object ID. It must identify achore(release)commit, optionally with a GitHub squash suffix such as(#123).--branchselects a maintenance/release branch. Otherwise the target commit’srelease_branchapplies, then main/master fallback in the local or remote namespace being checked.--packageis repeatable and selects released packages in a monorepo; root tags are omitted when selecting packages. Without it, all entries in the release subject are tagged, not every package in the workspace.--signcreates signed tags. Existing signatures are inspected and their trust-verification results reported separately; signature presence is not a verified signer-trust claim.--pushrequires a configured remote name with one identical effective fetch and push URL. Mirror remotes, shallow repositories and partial clones are refused. Required Git capabilities are checked before work.--dry-run --pushreads remote state and may fetch objects, but changes no refs, working files, index or FETCH_HEAD.--format jsonreports the target, branch, tag states, actions and diagnostics. Exit 0 means the requested work is satisfied, 1 a policy/input-state refusal, and 2 an operational failure or partial/uncertain completion.
Verify and recover
After publication, verify the remote tag object and that its peeled commit is reachable from the remote release branch. Report local bump, pushed refs, release CI, GitHub Release creation and package publication as separate states. A pushed tag is not proof that CI or a registry publication succeeded.
On interruption, inspect local and remote refs before doing anything else.
Rerun git std tag with the same commit to finish missing tags or confirm a push
whose response was lost. Matching annotated tags are preserved. A lightweight
tag, different target, different annotation or distinct local/remote tag object
is a conflict, even when two tag objects peel to the same commit. Inspect and
resolve that conflict deliberately; the command never deletes or overwrites it.
If a signing operation or pre-push hook fails, some local tags may already exist. The error reports known state; no destructive rollback occurs. Do not repeat the bump to recover a tag push. Never move an already published protected version tag: fix forward with a new release. These workflows do not change hosting rulesets or disable repository validation.