Skills101

AdvancedGit & GitHub · Lesson 9 of 9 · Updated ·

Git Tags, GitHub Releases and Semantic Versioning (v1.4.2 Explained)

A customer says "the invoice page broke after Tuesday's update". Which code was running on Tuesday? If your team tags every release, the answer takes one command. This lesson covers Git tags, how to number versions with semantic versioning, and how to publish a release on GitHub.

1. What is a tag?

A branch is a label that moves forward with every new commit. A tag is a label that never moves: it permanently names one commit, such as "this is version 1.1.0".

Four commits in a row; tag v1.0.0 sits on commit b1e9528 and tag v1.1.0 on cb59cb8, while main and HEAD point at the newest commit 0417847. git describe --tags gives v1.1.0-2-g0417847

BranchTag
Moves when you commit?yesno
Typical namemain, fix/loginv1.4.0
Used forongoing workmarking releases and milestones

2. Lightweight vs annotated tags

Git has two kinds of tags:

git tag v1.0.0 b1e9528                       # lightweight: just a name for a commit
git tag -a v1.1.0 -m "Release 1.1.0: coupons"  # annotated: a full tag object

An annotated tag is stored as its own object with the tagger's name, date and a message. You can check the type:

git cat-file -t v1.0.0
git cat-file -t v1.1.0
commit
tag

The lightweight tag points straight at a commit; the annotated tag is a tag object. git show v1.1.0 --no-patch starts with the tag details, followed by the commit it points to:

tag v1.1.0
Tagger: Asha <a@e.com>
Date:   Tue Nov 17 22:39:36 2026 +0530

Release 1.1.0: coupons

Use annotated tags for releases. They record who made the release and when, and many tools (including git describe without --tags) only look at annotated tags. Lightweight tags are fine for private bookmarks.

3. Working with tags

TaskCommand
List tagsgit tag
List matching tagsgit tag -l "v1.*"
Tag an older commitgit tag -a v0.9.0 <commit> -m "…"
Push one taggit push origin v1.1.0
Push all tagsgit push origin --tags
Delete a local taggit tag -d v1.1.0
Delete a tag on GitHubgit push origin --delete v1.1.0
Look at the code of a releasegit switch --detach v1.0.0
Start a fix branch from a releasegit switch -c hotfix/1.0.1 v1.0.0

Important: git push does not push tags by default. Forgetting to push them is the most common tag mistake.

Checking out a tag puts you in detached HEAD — you are on a commit, not a branch. That is fine for looking around. If you want to make changes, create a branch from the tag first (last row of the table).

4. Which version am I running? git describe

git describe --tags
v1.1.0-2-g0417847

Read it in three parts:

  • v1.1.0 — the nearest tag behind the current commit
  • 2 — the current commit is 2 commits after that tag
  • g0417847 — g (for Git) plus the short id of the current commit

Many teams print this string in the app's footer or a /version endpoint, so a bug report can say exactly which build it came from. If the current commit is itself tagged, git describe prints just the tag name.

5. Semantic versioning: MAJOR.MINOR.PATCH

Semantic versioning (semver, defined at semver.org) gives each part of a version number a meaning:

Starting from 2.4.1: a bug fix only makes 2.4.2, a new backward-compatible feature makes 2.5.0, and a breaking change makes 3.0.0; bumping a bigger part resets smaller parts to 0

PartIncrease it whenExample change
MAJORyou make a breaking change: old code using your API stops workingrenaming an API field
MINORyou add a feature that keeps old code workingadding UPI as a payment option
PATCHyou only fix bugs, without changing behaviour that users depend onfixing a wrong GST total

Rules worth remembering:

  • Increasing one part resets the smaller parts to 0: 2.4.1 → 2.5.0, not 2.5.1.
  • Versions starting with 0 (like 0.7.3) mean early development: anything may change at any time.
  • Extra labels mark pre-releases: 3.0.0-beta.1 comes before 3.0.0.
  • Git tags usually add a v: tag v2.5.0 for version 2.5.0.

Here is the bump rule as code:

function bump(version, part) {
  let [major, minor, patch] = version.split(".").map(Number);
  if (part === "major") return `${major + 1}.0.0`;
  if (part === "minor") return `${major}.${minor + 1}.0`;
  return `${major}.${minor}.${patch + 1}`;
}

console.log(bump("2.4.1", "patch"));
console.log(bump("2.4.1", "minor"));
console.log(bump("2.4.1", "major"));
2.4.2
2.5.0
3.0.0

Why this matters in practice

In package.json, "express": "^4.18.2" means "any version from 4.18.2 up to, but not including, 5.0.0". npm trusts that minor and patch updates do not break your code. When a library breaks semver, thousands of projects break at once — which is why getting the version number right is a real responsibility.

Versions are numbers, not text

Sorting tags as plain text gives the wrong order, because "1" < "2" character by character:

const tags = ["v1.10.0", "v1.2.0", "v1.9.3"];
console.log([...tags].sort());
const asNumbers = (t) => t.slice(1).split(".").map(Number);
console.log([...tags].sort((a, b) => {
  const x = asNumbers(a), y = asNumbers(b);
  return x[0] - y[0] || x[1] - y[1] || x[2] - y[2];
}));
[ 'v1.10.0', 'v1.2.0', 'v1.9.3' ]
[ 'v1.2.0', 'v1.9.3', 'v1.10.0' ]

Git has the same problem: plain git tag sorts as text. Use git tag --sort=v:refname to sort by version.

6. GitHub releases and changelogs

A tag is a Git feature. A release is a GitHub page built on a tag, with:

  • a title and release notes (what changed, in plain words)
  • downloadable files (for example a built .apk or .zip)
  • automatic source-code archives

To create one: repository → Releases → Draft a new release → choose or create a tag → write notes → Publish. GitHub can also generate release notes from the merged pull requests since the previous tag.

Many projects also keep a CHANGELOG.md with sections per version:

## 2.5.0
### Added
- UPI payments at checkout
### Fixed
- GST total rounded wrongly on invoices

7. A simple release routine

git switch main && git pull
# make sure tests pass and the version number in package.json is updated
git tag -a v2.5.0 -m "Release 2.5.0: UPI payments"
git push origin main
git push origin v2.5.0
# then create the GitHub release from tag v2.5.0

Automated pipelines (for example GitHub Actions) are often set to deploy whenever a tag starting with v is pushed, so the tag itself becomes the "ship it" button.

Common mistakes

  • Creating a tag but never pushing it (git push skips tags).
  • Moving or re-using a tag that others already fetched — create a new version instead.
  • Bumping PATCH for a breaking change, so users' code breaks on a "safe" update.
  • Making changes in detached HEAD after checking out a tag, then losing them; create a branch first.

Quick recap

  • A tag is a fixed label on a commit; branches move, tags do not.
  • Use annotated tags (git tag -a v1.2.0 -m "…") for releases; push them explicitly.
  • git describe --tags → nearest tag, commits since it, and the current short id.
  • Semver: MAJOR (breaking) . MINOR (new, compatible) . PATCH (fixes); bigger bumps reset smaller parts to 0.
  • A GitHub release = a tag + notes + files; keep a changelog.

Practice what you learned

📝 Quiz: Tags, Releases and Versioning5 questions · instant answers & explanations · +10 XP · counts towards your free certificateTake the quiz →