Git tags name selected objects, commonly commits associated with releases. They can make a release reference easy to communicate, but a familiar tag name is not by itself proof of source identity, authorization, or artifact content. A release workflow needs to verify what the tag points to and who may publish or change it.
This guide explains lightweight and annotated tags, signing, remote publication, and recovery. The goal is a trustworthy release reference rather than assuming the word version makes a mutable name permanently reliable.
Define the release object before naming it
Identify the exact approved commit and acceptance evidence. Tests, review, and relevant artifact checks should precede the release label. A tag added to an unreviewed branch tip does not retroactively approve the code.
Use the commit identifier when verifying the intended target. A branch name can move between discussion and tagging. Record the selected object in the release manifest where the workflow requires it.
Check the working tree separately. Tagging a commit does not include uncommitted edits or untracked files that happened to make a local build succeed. Release builds need a controlled source state.
Distinguish lightweight and annotated tags
A lightweight tag is a reference to an object without a separate annotated tag object. An annotated tag stores metadata and a message in a tag object and can support signing under Git’s documented mechanisms.
Choose the type from the release policy. An informal local bookmark and a published release record have different needs. Do not assume a tag name alone tells a recipient which type was used.
Inspect the target and metadata through supported Git commands. A tag can refer to objects beyond the usual commit case. The release workflow should verify the expected object type and peeled commit identity.
Make naming policy predictable
Use a consistent release naming convention and avoid ambiguous names that can collide with branch references in tools. Document whether prereleases and maintenance releases have distinct formats.
Treat a version name as an application convention rather than proof of semantic compatibility. Git does not enforce that a major or patch label matches the actual change. Reviewers must verify the release meaning.
Keep the policy compatible with build and deployment tooling. A CI rule matching tags can trigger consequential actions. Test what names qualify instead of assuming only intended releases can activate it.
Verify signatures with the right trust model
A signed annotated tag can provide evidence about the tag object under the configured signing mechanism. Verification requires the appropriate trusted identity and supported tooling, not merely a message that some signature exists.
Review key or signer trust, revocation handling, and the expected release authority. A valid signature from an unapproved signer should not authorize deployment. Cryptographic validity and organizational approval are separate checks.
Do not claim a signed tag proves the built binary contains exactly that source. Build provenance and artifact verification need their own evidence. The tag identifies a source reference, not every downstream transformation.
Publish the intended reference explicitly
Creating a local tag does not automatically publish it to a remote. Use the supported explicit push workflow and confirm the remote points to the intended object. Review broad tag-push behavior before using it.
Avoid sending unrelated local tags by convenience. They may be obsolete, experimental, or contain metadata not intended for the remote audience. Publish only the approved release references.
Check remote permissions and protection rules where supported. A release name is more dependable when publication and replacement authority are restricted rather than available to every contributor.
Treat published tags as stable release references
Adopt an immutable release-tag policy where appropriate. Moving a published tag can leave different users and caches with different source identities under the same name. A force update is a collaboration and supply-chain event.
If an incorrect release tag was published, use the team’s controlled correction process. Explain the mistake and publish a new unambiguous release reference where the policy requires it. Do not silently rewrite history consumers may trust.
Verify downstream systems after a correction. Package registries, deployment caches, and release pages may retain earlier artifacts even if the Git reference changes. Git state alone is not the whole release estate.
Map artifacts to the approved commit
Build from a controlled source state and record the exact commit and relevant build inputs. A package filename matching the tag name is not sufficient evidence that the artifact was produced from it.
Use the approved provenance and signing workflow for artifacts where required. Dependency identity, build environment, and generated content can change the result independently of the tagged commit.
Keep secrets out of tag messages and release metadata. Annotated history can be retained and widely fetched. A release record should explain the change without embedding private operational credentials or customer data.
Verify fetch and checkout behavior
Recipients should inspect the expected remote, tag object, and commit identity before building or deploying. Fetch behavior depends on the command and ref configuration; do not assume every local tag is current or authoritative.
Checking out a tag commonly produces a detached-HEAD state. That is suitable for inspection, but new work should use an intentional branch or another controlled workflow. Avoid losing track of experimental commits made from a release snapshot.
Run relevant acceptance checks through the actual deployment process. A verified tag can still identify a release incompatible with the current configuration or data. Source authenticity does not eliminate rollout testing.
Maintain recovery and release inventory
Retain the required tag objects, source history, artifacts, and verification material according to the recovery policy. A tag reference without reachable objects or accessible artifacts is not a complete release restore.
Periodically test retrieval of an older approved release in a controlled environment. Confirm its source identity and compatible dependencies. Record limitations when external services or keys have changed.
For a production release, select an approved commit, create an annotated tag, verify authorized signing, publish explicitly, and bind artifacts to the commit. That sequence gives the version name an evidence-backed meaning.
Frequently asked questions
Does a local tag automatically appear remotely?
No. Publication needs an appropriate explicit remote update.
Does a signature prove the artifact matches the source?
No. Artifact and build provenance require separate verification.
Where are tag types and signing options explained?
Read Git’s tagging guide and the supported command documentation for your signing workflow.
For a complementary workflow, read Git Commit Signing: Verify Identity Without Overclaiming.
