Git Tags and Releases Best Practices: A Complete Guide

Git Tags and Releases Best Practices

Updated November 16, 2026. I re-ran every Git command on this page on Git 2.56.1 in a throwaway repository, and added the sections on tags vs releases, version sorting, hotfixes from an old tag, and release candidates.

A Git tag is a permanent name for one commit, usually a version like v1.4.0. A GitHub release is a page built on top of a tag, with release notes and downloadable files. Use annotated tags for releases, push them with git push --follow-tags, and let CI create the release so every version is built and documented the same way.

This guide covers Git tags and releases best practices, the tag commands you will actually use, how to fix tagging mistakes, how to protect release tags, and a current GitHub Actions workflow that publishes a release on every version tag. It is part of our complete Git and GitHub Actions workflow guide.

Choosing how releases fit your branching model? See Git Flow vs GitHub Flow vs trunk-based development.

In this guide:

  • How a Git tag differs from a GitHub release
  • The tag commands you will use, including version-order listing
  • How to fix a tag on the wrong commit, before and after pushing
  • Release tag dos and don’ts, and a GitHub Actions release workflow

Git Tags vs GitHub Releases: What Is the Difference?

A tag belongs to Git. A release belongs to GitHub and always points at a tag. You can have tags without releases, but not a release without a tag.

Git tag GitHub release
Lives in The repository, on every clone GitHub only
What it is A name for one commit A page attached to a tag
Holds Tagger, date, message, optional signature Release notes, uploaded files, pre-release and latest flags
Created with git tag The web UI, gh release create, or CI
Moves to GitLab or Bitbucket with a push Yes No
Source archives None of its own GitHub adds zip and tar.gz downloads of the tagged commit

In practice: tag every version, and publish a release for the versions people download or read notes for. GitHub’s About releases page describes the release side. Pushing a tag does not create a release on its own. You need the UI, the CLI or a workflow for that, and both are shown below.

Lightweight vs Annotated Tags

Lightweight Annotated
What it stores Just a pointer to a commit A full Git object: tagger, date, message, optional signature
Create git tag v1.0.0 git tag -a v1.0.0 -m "Release 1.0.0"
Pushed by --follow-tags No Yes
Used by git describe by default No Yes
Use for Private, temporary markers Releases

Always use annotated tags for releases. They record who tagged the release and when, and several Git features ignore lightweight tags by default. The git tag documentation lists every option.

Everyday Tag Commands

git tag                          # list tags
git tag -l "v1.*"                # list matching tags
git tag -n1                      # list tags with the first line of each message
git show v1.0.0                  # show the tag and its commit

git tag -a v1.1.0 -m "Release 1.1.0"            # tag the current commit
git tag -a v1.0.1 abc1234 -m "Release 1.0.1"    # tag a specific commit

git push origin v1.1.0           # push one tag
git push --follow-tags           # push commits plus their annotated tags

git tag -d v1.1.0                # delete locally
git push origin --delete v1.1.0  # delete on the remote

git describe --tags              # e.g. v1.1.0-3-g9f2c1ab (3 commits after v1.1.0)
git describe --tags --abbrev=0   # just the nearest tag name, e.g. v1.1.0

Prefer git push --follow-tags over git push --tags. --tags pushes every local tag, including throwaway lightweight ones. In my test repo it uploaded a scratch tag called tmp-light that --follow-tags had correctly left behind. --follow-tags only pushes annotated tags that point at commits you are pushing. You can make it the default with git config --global push.followTags true.

Listing Tags in Version Order

Plain git tag sorts as text, so v1.10.0 lands before v1.2.0. Sort by version instead:

git tag --sort=-v:refname        # newest version first

There is one catch with pre-release tags. With default settings my test repo listed v1.2.0-rc.1 above v1.2.0, as if the release candidate were newer than the final release:

v1.10.0
v1.2.0-rc.1
v1.2.0
v1.0.0

Tell Git that a - suffix means “earlier than the plain version” and the order is right:

git config --global versionsort.suffix -
git tag --sort=-v:refname
v1.10.0
v1.2.0
v1.2.0-rc.1
v1.0.0

To see when each tag was made and whether it is annotated (tag) or lightweight (commit):

git for-each-ref --sort=-creatordate \
  --format='%(refname:short) %(creatordate:short) %(objecttype)' refs/tags

Checking Out a Tag and Patching an Old Release

git checkout v1.0.0 works, but it puts you in a detached HEAD state: fine for looking around or building that version, not for new commits. To fix a bug in an old release, start a branch from the tag:

git switch -c hotfix/1.0.1 v1.0.0
# fix, commit, then:
git tag -a v1.0.1 -m "Release 1.0.1"
git push --follow-tags origin hotfix/1.0.1

To check which tags already include a given fix, use git tag --contains <commit>.

Signed Tags

git tag -s v1.2.0 -m "Release 1.2.0"   # sign with your GPG or SSH key
git tag -v v1.2.0                      # verify the signature

Signed tags prove the release came from you. GitHub shows a “Verified” badge on signed tags if your signing key is added to your account. With SSH signing, set git config --global gpg.format ssh and point user.signingkey at your public key.

Fixing Tag Mistakes

Tagged the wrong commit (not pushed yet)

git tag -d v1.0.0
git tag -a v1.0.0 <correct-commit> -m "Release 1.0.0"

Tagged the wrong commit (already pushed)

git tag -d v1.0.0
git push origin --delete v1.0.0
git tag -a v1.0.0 <correct-commit> -m "Release 1.0.0"
git push origin v1.0.0

If you skip the delete and just push the moved tag, the remote refuses it:

 ! [rejected]        v1.2.0 -> v1.2.0 (already exists)
hint: Updates were rejected because the tag already exists in the remote.

Warning: Moving a pushed tag does not update anyone else’s copy. Anyone who already fetched the old tag keeps it.

When I moved a pushed tag and ran git fetch --tags in a second clone, Git refused to replace the local copy:

 ! [rejected] v1.0.0     -> v1.0.0  (would clobber existing tag)

Every teammate and CI cache would need git fetch --tags --force to pick up the new one. If the version has been downloaded or deployed, it is usually better to leave it and release v1.0.1 instead.

Tag not showing on the remote

Tags are not pushed by a plain git push. Push it by name, or use --follow-tags.

Git Tags and Releases Best Practices: Dos and Don’ts

Do Don’t
Use semantic versioning with a v prefix: v2.3.1 Mix schemes like 1.0, release-2 and v3 in one repository
Use annotated tags for every release Release from lightweight tags, which carry no author, date or message
Tag a commit on main after it has merged and passed CI Tag a feature branch commit that may never reach main
Push with --follow-tags Push with --tags and upload every scratch tag you have
Ship a mistake fix as a new patch version Move or delete a tag that people have already fetched
Mark test builds as pre-releases: v2.0.0-rc.1 Reuse the final version number for a build that is still being tested
Let CI build and publish the release Upload hand-built files from a laptop

Three more that do not fit in a table:

  • Protect release tags. On GitHub, add a repository ruleset targeting tags matching v* that restricts who can create, update or delete them.
  • Consider immutable releases. When enabled on GitHub, a published release’s tag and assets cannot be changed or deleted, which protects users from tampered downloads.
  • Put the “why” in the release notes, not the tag message. The tag message can stay one line (“Release 1.1.0”). Notes are easier to edit later, and a tag message cannot be changed without moving the tag.

Release Candidates and Pre-Release Tags

For a version that needs testing before it is final, tag a release candidate and mark the GitHub release as a pre-release, so it is not shown as the latest version:

git tag -a v2.0.0-rc.1 -m "Release candidate 1 for 2.0.0"
git push origin v2.0.0-rc.1
gh release create v2.0.0-rc.1 --prerelease --generate-notes

When testing passes, tag the same commit, or the commit with the last fixes, as v2.0.0. Leave the rc tags in place as a record of what was tested.

Creating a GitHub Release

From the web UI: Releases → Draft a new release → choose or create a tag → click Generate release notes → publish. From the terminal, the GitHub CLI does the same in one line:

gh release create v1.1.0 --generate-notes
gh release create v1.1.0 ./dist/app.tar.gz --generate-notes   # with an attached file
gh release create v1.1.0 --generate-notes --verify-tag        # stop if the tag is not on GitHub yet

Without --verify-tag, gh release create makes the tag for you if it is missing, from the latest state of the default branch. Its help text says to create and push the tag yourself if you want an annotated one, so for releases I push my own annotated tag first and add --verify-tag.

Automating Releases with GitHub Actions

This workflow creates a GitHub release with auto-generated notes every time you push a tag starting with v:

name: Release
on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Create GitHub release
        uses: softprops/action-gh-release@v3
        with:
          generate_release_notes: true

The permissions: contents: write block matters. Repositories created in recent years give GITHUB_TOKEN read-only access by default, and without it the release step fails with a 403 error. To attach build output, add a build step and pass its files to the action with files: dist/*. For more on workflow syntax, see our GitHub Actions workflow YAML guide.

Your release flow then becomes two commands:

git tag -a v1.1.0 -m "Release 1.1.0"
git push --follow-tags

Quick Summary:

  • A tag is a name for a commit in Git; a GitHub release is a page attached to a tag
  • Use annotated tags for releases and push them with git push --follow-tags
  • Set versionsort.suffix to - so v1.2.0-rc.1 sorts before v1.2.0
  • Do not move a tag that others have fetched; release a new patch version
  • Let a workflow create the release on every v* tag, with contents: write

What I Did Not Test

I ran the Git commands locally against a bare repository standing in for the remote. I did not re-run the GitHub Actions workflow or the gh release commands for this update; the gh flags are from gh release create --help on gh 2.104.0, and the workflow is the one I last checked in September 2026.

Frequently Asked Questions

Q: What is the difference between a Git tag and a GitHub release?
A: A Git tag is a name for one commit and lives in the repository. A GitHub release is a page on GitHub attached to a tag, with release notes and downloadable files. Every release has a tag, but a tag does not need a release.

Q: What is the difference between a lightweight and an annotated Git tag?
A: 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.

Q: How do I push tags to a remote?
A: Run git push origin TAGNAME to push one tag, or git push –follow-tags to push your commits together with their annotated tags. git push –tags also works but pushes every local tag, including temporary ones.

Q: How do I delete a Git tag?
A: Run git tag -d TAGNAME to delete it locally, then git push origin –delete TAGNAME to remove it from the remote.

Q: Can I move a Git tag to a different commit?
A: Yes, by deleting and recreating it, but moving a published tag is discouraged. Clones that already fetched it keep the old one until they run git fetch –tags –force, so release a new patch version instead.

Q: Should I tag on main or on a release branch?
A: Tag the commit that was actually built and shipped. With GitHub Flow or trunk-based development that is a commit on main after CI passes. With release branches or hotfixes, tag the tip of that branch.


Get the next guide by email

New DevToolHub guides on Git, GitHub Actions, Claude Code and cloud tools, emailed as they publish: about one a weekday. I run the commands before I write them up. The Git + GitHub Actions cheat sheet is a free PDF, no signup needed.

You Might Also Like