A branch moves every time someone commits. A tag is a name that stays on one commit forever, which makes it the natural way to mark releases: “this exact commit is Orbit 1.4.0”. Container images, Helm charts, changelogs and deploy pipelines all hang off tags, so a team that tags carefully always knows what runs in production.
Lightweight and annotated tags
Git has two kinds of tags:
| Lightweight | Annotated | |
|---|---|---|
| What it is | Just a name pointing at a commit | A full object with tagger, date and message |
| Created with | git tag v1.4.0 | git tag -a v1.4.0 -m "message" |
| Can be signed | No | Yes |
Shown by git describe | Only with --tags | Yes |
| Use for | Private, temporary bookmarks | Releases |
Use annotated tags for releases. They record who tagged and when, and they are what most tools expect.
$ git tag -a v1.4.0 -m "Orbit 1.4.0: full-text search and faster login"
$ git tag
v1.2.0
v1.3.0
v1.4.0
$ git show v1.4.0
tag v1.4.0
Tagger: Ana Souza <ana@orbit.dev>
Date: Fri Nov 6 11:02:14 2026 -0300
Orbit 1.4.0: full-text search and faster login
commit 90bd114e...
Versioning with SemVer
Most projects name release tags with semantic versioning, vMAJOR.MINOR.PATCH:
| Part | Increase when | Example |
|---|---|---|
| MAJOR | You make a breaking change | v1.9.3 to v2.0.0 |
| MINOR | You add a feature that stays compatible | v1.4.0 to v1.5.0 |
| PATCH | You fix a bug, nothing else | v1.4.0 to v1.4.1 |
Pre-releases add a suffix: v2.0.0-rc.1, v2.0.0-beta.2. Some teams use date-based versions instead (2026.11.0); what matters is choosing one scheme and sticking to it.
Listing and finding tags
$ git tag -l "v1.4.*" # filter by pattern
v1.4.0
v1.4.1
$ git tag --sort=-v:refname | head -3 # newest version first
$ git tag --contains 7aa0f21 # which releases include this commit?
$ git log --oneline v1.3.0..v1.4.0 # what changed between two releases
The last command is the raw material for a changelog: every commit between two tags.
Tagging an older commit
Forgot to tag the release last week? Tag the commit by its ID:
$ git log --oneline --grep="Release"
5c90e3d Release 1.3.1
$ git tag -a v1.3.1 5c90e3d -m "Orbit 1.3.1"
Pushing tags
git push does not send tags by default. Push them explicitly:
$ git push origin v1.4.0 # one tag
$ git push --follow-tags # commits plus the annotated tags that point at them
$ git config --global push.followTags true
Avoid git push --tags as a habit: it pushes every local tag, including throwaway lightweight ones. Fetching gets tags automatically along with the commits they point to.
Deleting and fixing tags
$ git tag -d v1.4.0 # delete locally
$ git push origin --delete v1.4.0 # delete on the remote
Warning: Never move a release tag that others may have fetched. Git does not update tags that already exist on other machines, so their v1.4.0 would silently differ from yours, and caches like container registries keep the old one. If a release is broken, publish v1.4.1.
Signed tags
A signed tag proves who created the release. With SSH signing set up (lesson 17):
$ git tag -s v1.4.0 -m "Orbit 1.4.0"
$ git tag -v v1.4.0
Good "git" signature for ana@orbit.dev with ED25519 key SHA256:...
GitHub and GitLab show signed tags as Verified, and supply-chain tooling can refuse unsigned releases.
git describe: versions for builds
git describe names the current commit relative to the latest annotated tag. It is a great way to stamp a build version:
$ git describe
v1.4.0-3-g8c2e01a
$ git describe --tags --dirty --always
v1.4.0-3-g8c2e01a-dirty
Read v1.4.0-3-g8c2e01a as “three commits after v1.4.0, at commit 8c2e01a”. --dirty adds a suffix when there are uncommitted changes; --always falls back to the commit ID when no tag exists.
Tags in CI/CD
Tags are the usual release trigger. A pipeline can build on every push but deploy only when a version tag appears. In GitLab CI:
release:
stage: deploy
script:
- docker build -t registry.example.com/orbit/api:$CI_COMMIT_TAG .
- docker push registry.example.com/orbit/api:$CI_COMMIT_TAG
rules:
- if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
The CI/CD Tutorial builds complete release pipelines like this one. Many teams also protect release tags in the hosting service so only maintainers can create them.
Quick reference
| Task | Command |
|---|---|
| Annotated tag | git tag -a v1.4.0 -m "message" |
| Tag an older commit | git tag -a v1.3.1 <commit> -m "message" |
| List / filter | git tag / git tag -l "v1.*" |
| Show a tag | git show v1.4.0 |
| Changes between releases | git log --oneline v1.3.0..v1.4.0 |
| Push one tag / with commits | git push origin v1.4.0 / git push --follow-tags |
| Delete local / remote | git tag -d v1.4.0 / git push origin --delete v1.4.0 |
| Signed tag | git tag -s v1.4.0 -m "message" |
| Version string for builds | git describe --tags --dirty --always |
Exercise
You are tagging an official release of Orbit. Which command fits best?
Show answer
Answer: C. An annotated tag stores the tagger, date and message and can be signed, which is what release tooling and git describe expect. A lightweight tag is only a bare name, and a branch would move with new commits.
Exercise
You created tag v1.5.0 and ran git push. The tag does not appear on GitHub. Why?
Show answer
Answer: D. By default git push sends branch commits only. Push the tag with git push origin v1.5.0, or use git push –follow-tags (or push.followTags) to send annotated tags along with commits.
Exercise
Release v1.4.0 was published yesterday and has a bug. What is the safe way to ship the fix?
Show answer
Answer: A. Other clones, registries and caches already have v1.4.0 and will not pick up a moved tag, so its meaning would differ between machines. A new patch version is clear to everyone.
Key takeaways
- Tags are fixed names for commits; use annotated tags (
-a) for releases. - SemVer (
vMAJOR.MINOR.PATCH) tells users what kind of change a release contains. git pushdoes not push tags; usegit push origin <tag>or--follow-tags.- Never move a published tag; release a new version instead.
- Signed tags prove authorship,
git describestamps build versions, and CI pipelines release on version tags.
FAQ
What is the difference between a tag and a branch?
Both point to a commit. A branch moves forward with each new commit on it; a tag never moves. Use branches for ongoing work and tags for fixed points such as releases.
Can I check out a tag and work on it?
git switch --detach v1.4.0 puts you on that commit in detached HEAD (lesson 4). To fix an old release, create a branch from it: git switch -c hotfix/1.4.1 v1.4.0.
Why does git describe say “No names found”?
There are no annotated tags in the history of the current commit. Create one, use --tags to consider lightweight tags, or add --always to fall back to the commit ID.
Should tag names start with v?
It is a convention, not a rule. v1.4.0 is the most common style and many tools recognise it. Whatever you choose, be consistent so sorting and pipeline rules work.
How do I get tags that someone else pushed?
A normal git fetch downloads tags that point at commits you fetch. To fetch every tag, run git fetch --tags.