Lesson 10 beginner

Git Tagging

Mark releases with tags: lightweight versus annotated tags, semantic versioning, tagging older commits, pushing and deleting tags, signed tags, git describe for build versions and how CI pipelines use tags to trigger releases.

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:

LightweightAnnotated
What it isJust a name pointing at a commitA full object with tagger, date and message
Created withgit tag v1.4.0git tag -a v1.4.0 -m "message"
Can be signedNoYes
Shown by git describeOnly with --tagsYes
Use forPrivate, temporary bookmarksReleases

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:

PartIncrease whenExample
MAJORYou make a breaking changev1.9.3 to v2.0.0
MINORYou add a feature that stays compatiblev1.4.0 to v1.5.0
PATCHYou fix a bug, nothing elsev1.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

TaskCommand
Annotated taggit tag -a v1.4.0 -m "message"
Tag an older commitgit tag -a v1.3.1 <commit> -m "message"
List / filtergit tag / git tag -l "v1.*"
Show a taggit show v1.4.0
Changes between releasesgit log --oneline v1.3.0..v1.4.0
Push one tag / with commitsgit push origin v1.4.0 / git push --follow-tags
Delete local / remotegit tag -d v1.4.0 / git push origin --delete v1.4.0
Signed taggit tag -s v1.4.0 -m "message"
Version string for buildsgit describe --tags --dirty --always

Exercise

You are tagging an official release of Orbit. Which command fits best?

  1. git tag v2.0.0
  2. git branch v2.0.0
  3. git tag -a v2.0.0 -m “Orbit 2.0.0”
  4. git commit –tag v2.0.0
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?

  1. Tags can only be created in the GitHub web interface
  2. The tag must be lightweight to be pushed
  3. The tag name must not start with v
  4. git push does not send tags unless you push them explicitly or use –follow-tags
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?

  1. Commit the fix and release it as v1.4.1
  2. Delete v1.4.0 and create it again on the fixed commit
  3. Force-push the tag to the new commit
  4. Rename v1.4.0 to v1.4.0-broken
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 push does not push tags; use git push origin <tag> or --follow-tags.
  • Never move a published tag; release a new version instead.
  • Signed tags prove authorship, git describe stamps 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.

↑ ↓ navigate Enter open Esc close