Git Tags and Releases Best Practices: A Complete Guide

Amaresh Pelleti
Git Tags and Releases Best Practices

Version control is not just about tracking changes — it’s also about managing software releases effectively. In Git, this is done using tags and releases.

This article is part of our complete Git and GitHub Actions workflow guide.

Tags mark important points in your project’s history, such as a v1.0.0 release, while GitHub (and similar platforms) allow you to turn those tags into official releases with notes, changelogs, and downloadable assets.

In this post, we’ll cover:

  • What Git tags are
  • Types of tags (lightweight vs annotated)
  • Commands to create, push, and delete tags
  • Tagging branches for releases
  • Troubleshooting tags
  • Best practices for tagging
  • How to create releases on GitHub
  • Automating releases with CI/CD

1. What Are Git Tags?

A tag in Git is like a bookmark pointing to a specific commit. Unlike branches, tags don’t move—they are permanent references.

They’re most often used to mark version numbers (e.g., v1.0.0, v2.5.3) in a project.

2. Types of Git Tags

🔹 Lightweight Tags

  • Just a pointer to a commit (like a branch without history).
  • Used for quick, temporary markers.

Command:

git tag v1.0.0

🔹 Annotated Tags

  • Stored as full Git objects with metadata (tagger, date, message, etc.).
  • Recommended for releases.

Command:

git tag -a v1.0.0 -m "Release version 1.0.0"

3. Managing Tags

List all tags:

git tag

Show details of a tag:

git show v1.0.0

Push a single tag to remote:

git push origin v1.0.0

Push all local tags to remote:

git push --tags

Delete a local tag:

git tag -d v1.0.0

Delete a remote tag:

git push origin --delete v1.0.0

4. Tagging a Branch or Specific Commit

Sometimes you want to tag a commit that’s not on main (e.g., a feature branch).

Tag the latest commit on a branch:

git checkout feature-branch
git tag -a v2.0.0-beta -m "Beta release from feature branch"

Tag a specific commit by hash:

git tag -a v1.1.0 abc1234 -m "Release 1.1.0"

5. Troubleshooting Git Tags

🔹 Accidentally tagged the wrong commit?

Delete and re-create the tag:

git tag -d v1.0.0
git push origin --delete v1.0.0
git tag -a v1.0.0 new_commit_hash -m "Corrected tag"
git push origin v1.0.0

🔹 Tag not showing on remote?

Make sure you pushed it:

git push origin v1.0.0

🔹 Accidentally pushed all tags?

Remove unwanted ones from remote:

git push origin --delete old-tag

6. Best Practices for Git Tags

✅ Always use annotated tags for releases
✅ Follow semantic versioning (MAJOR.MINOR.PATCH)
✅ Prefix versions with v (e.g., v1.2.0) for consistency
✅ Tag only stable commits that pass CI/CD checks
✅ Automate tagging and releasing through pipelines

7. GitHub Releases

On GitHub, tags can be turned into releases.

A release includes:

  • A tag reference
  • Release notes (changelog)
  • Downloadable source code or binaries

Steps:

  1. Go to Releases in your GitHub repo.
  2. Click “Draft a new release.”
  3. Select a tag (or create a new one).
  4. Add release notes.
  5. Publish release.

8. Automating Releases with CI/CD

You can automate tagging and releases with tools like GitHub Actions, GitLab CI, or Jenkins.

Example: GitHub Action for tagging and releasing

name: Release
on:
  push:
    tags:
      - 'v*'
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          generate_release_notes: true

This workflow automatically creates a release every time a new tag (v*) is pushed.

9. Conclusion

Git tags and releases are essential for managing versioned software. By using annotated tags, following semantic versioning, tagging the right commits/branches, and troubleshooting mistakes quickly, you’ll keep your release process smooth.

Start tagging your next release with best practices—it will make collaboration and deployment much easier 🚀

Frequently Asked Questions

What is the difference between a lightweight and an annotated Git tag?

A lightweight tag is just a pointer to a commit; an annotated tag is a full object storing the tagger, date, message and an optional signature. Use annotated tags for releases.

How do I push tags to a remote?

Run git push origin TAGNAME to push one tag, or git push origin –tags to push all local tags.

How do I delete a Git tag?

Run git tag -d TAGNAME to delete it locally, then git push origin –delete TAGNAME to remove it from the remote.

Can I move a Git tag to a different commit?

Yes, with git tag -f TAGNAME COMMIT and a force push, but moving a published tag is discouraged because existing clones keep the old one.

You Might Also Like