How to Create a Git Release Tag

Q: What's the difference between an annotated and lightweight git tag?

An annotated tag (`git tag -a`) stores a message, author, and date and is a real git object - use it for releases. A lightweight tag is just a name pointing at a commit, with no metadata.

Q: How do I tag an older commit in git?

Pass the commit to the tag command: `git tag -a v1.0.0 -m "..." ` (or `HEAD~1` for the second-to-last commit). Without a commit it tags HEAD.

Q: Why isn't my git tag on the remote?

`git push` doesn't push tags by default. Push it explicitly with `git push origin v1.0.0` (or `git push origin --tags` for all of them).

A git tag marks a specific commit as a release. For releases you want an annotated tag (it stores a message, author, and date). Here's how to create one - even on an older commit - and push it.

Data Engineergittagrelease

Annotated vs lightweight tags

Annotated (git tag -a) - a full object with a message, tagger, and date. Use this for releases - it's what git describe and release tooling expect.
Lightweight (git tag name) - just a pointer to a commit, no metadata. Fine for a private bookmark, not for a release.

Create an annotated release tag

git tag -a v1.0.0 -m "v1.0.0 - first stable release"

This tags the current commit (HEAD). Follow semantic versioning - vMAJOR.MINOR.PATCH (v1.0.0, v1.2.3) - so tooling can sort and compare releases.

Tag a specific (older) commit

If the release commit isn't HEAD - say the latest commit is a WIP you don't want to ship - tag the right one explicitly:

git tag -a v1.0.0 -m "v1.0.0 - first stable release" <commit-sha>
# e.g. the second-to-last commit:
git tag -a v1.0.0 -m "v1.0.0 - first stable release" HEAD~1

Push the tag (it doesn't go automatically)

git push does not push tags. Push it explicitly:

git push origin v1.0.0      # one tag
git push origin --tags      # all tags

Inspect, move, delete

git tag                     # list tags
git show v1.0.0             # see the tag message + the commit it points to
git tag -d v1.0.0           # delete locally
git push origin :v1.0.0     # delete on the remote

Tags are immutable by convention - if you tagged the wrong commit, delete and re-create rather than "moving" a published tag, which confuses anyone who already pulled it.

Semantic versioning and a clean release flow

Tag names are the contract consumers read, so follow semantic versioning: vMAJOR.MINOR.PATCH (v1.4.2). Bump PATCH for fixes, MINOR for backward-compatible features, MAJOR for breaking changes. The v prefix is convention so tags sort and filter cleanly.

A repeatable flow:

Merge everything for the release to your main branch.
git tag -a v1.4.2 -m "Release 1.4.2" on that commit.
git push origin v1.4.2 (tags do not push with a normal git push).
On GitHub, that tag can back a Release with notes and artifacts.

Two safety rules: never move or delete a tag that has already been pushed and consumed - cut a new one instead, because others may have pinned to it. And tag the exact tested commit, not whatever HEAD happens to be, by passing the SHA: git tag -a v1.4.2 <sha>.

Want to try it hands-on? HeyDevJob gives you this exact setup in a live cloud workspace in your browser - edit it, run it, and see it work. Free, nothing to install.

Try it in a workspace →

What you'll practice

Creating an annotated tag with a message
Tagging a specific commit (not HEAD)
Pushing tags to the remote

FAQ

What's the difference between an annotated and lightweight git tag?

An annotated tag (git tag -a) stores a message, author, and date and is a real git object - use it for releases. A lightweight tag is just a name pointing at a commit, with no metadata.

How do I tag an older commit in git?

Pass the commit to the tag command: git tag -a v1.0.0 -m "..." <commit-sha> (or HEAD~1 for the second-to-last commit). Without a commit it tags HEAD.

Why isn't my git tag on the remote?

git push doesn't push tags by default. Push it explicitly with git push origin v1.0.0 (or git push origin --tags for all of them).

How do I release a tag in git?

Create an annotated tag (git tag -a v1.0.0 -m release), then push it with git push origin v1.0.0 - tags do not push by default. On GitHub that tag can back a Release.

What is the difference between a git tag and a release?

A git tag is a pointer to a specific commit (a version marker). A release is a platform feature like GitHub Releases built on top of a tag, adding notes, binaries, and a download page.

Keep learning

Make an ETL Pipeline IdempotentData project Speed Up a Slow SQL Report QueryData project Make a CSV Importer Resilient to Bad DataData project Data roadmapStep by step to hired Data interview questionsSTAR answers All Data projectsProjects hub

Learn it by doing. Open this in a live cloud workspace, make the change yourself, and keep a record of the work you can share.

Open the workspace →