Introduction

Git tags mark specific commits and are the foundation for many release workflows on GitHub. Teams use tags to create releases, trigger CI pipelines, and anchor changelogs to immutable commit references. A safe tagging process verifies commit target, tag type, and publication steps before announcing a release.

Tag Types and When to Use Them

Git supports lightweight and annotated tags.

Lightweight tags are just named pointers. Annotated tags include metadata such as message, creator, and timestamp. For production releases, annotated tags are usually preferred because they preserve release context.

Create both styles locally:

1# lightweight tag
2git tag v1.4.0
3
4# annotated tag
5git tag -a v1.4.0 -m "Release v1.4.0"

If automation or external users depend on tags, choose annotated by default.

Verify the Commit Before Tagging

Never tag blindly from current shell state. Confirm you are on the intended commit and branch.

git status
git branch --show-current
git log --oneline -n 5

If the release target is not HEAD, tag by commit hash explicitly.

git tag -a v1.4.0 <commit-sha> -m "Release v1.4.0"

This is common when releasing a maintenance patch from an older branch.

Push Tags to GitHub

Tags are local until pushed.

Push one tag:

git push origin v1.4.0

Push all local tags:

git push origin --tags

In shared repositories, pushing one explicit tag is safer than pushing all tags accidentally.

Create a GitHub Release From a Tag

A GitHub release builds on a tag by adding title, notes, and optional binaries. The tag remains the immutable code reference.

CLI example:

gh release create v1.4.0 \
  --title "v1.4.0" \
  --notes "Bug fixes and API stability updates"

You can also create releases in the GitHub UI by selecting the tag.

Correcting a Mistag

If you tag the wrong commit, fix both local and remote tags carefully.

1# delete local tag
2git tag -d v1.4.0
3
4# delete remote tag
5git push origin :refs/tags/v1.4.0
6
7# recreate correctly
8git tag -a v1.4.0 <correct-sha> -m "Release v1.4.0"
9git push origin v1.4.0

Retagging a published version can confuse downstream users and CI systems. Communicate corrections clearly in release channels.

Naming Conventions for Automation

Consistent naming helps tooling parse versions. A common convention is semantic versioning with v prefix:

• v1.0.0
• v1.2.3
• v2.0.0-rc1

Whatever convention you choose, document it and apply it uniformly.

Signed Tags for Trust and Provenance

For security-sensitive repositories, sign tags using GPG so consumers can verify authenticity.

git tag -s v1.4.0 -m "Signed release v1.4.0"
git tag -v v1.4.0

Signed tags improve supply-chain confidence and support stricter release governance.

Release Checklist Example

A practical release checklist:

1. Ensure working tree is clean.
2. Confirm release commit hash.
3. Create annotated or signed tag.
4. Push tag explicitly.
5. Publish GitHub release notes.
6. Verify CI and artifact publication.

A checklist prevents common release mistakes under deadline pressure.

Common Pitfalls

• Using lightweight tags for formal releases that need metadata.
• Tagging the wrong commit due to skipped verification.
• Forgetting to push tags and assuming GitHub already has them.
• Reusing published tag names without communication.
• Mixing inconsistent naming schemes that break release automation.

Summary

• Tags are critical release anchors in GitHub workflows.
• Prefer annotated or signed tags for production releases.
• Verify commit target before creating a tag.
• Push tags explicitly and publish release metadata.
• Treat retagging as a coordinated event to avoid downstream confusion.