Tags and Releases

Introduction

Tags mark specific commits—usually release versions like v1.0.0. They do not move when you add commits. This chapter creates lightweight and annotated tags, pushes them to remote, connects SemVer to Maven/Gradle/npm versions, and introduces GitHub Releases.

Prerequisites

Remote Repositories
GitHub and Pull Requests
Stable commit on main you want to mark as a release

Lightweight vs Annotated Tags

Lightweight tag

Pointer to commit—no extra metadata:

bash

git tag v1.0.0

Annotated tag (recommended for releases)

Includes tagger, date, message, can be GPG-signed:

bash

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

Code explanation:

-a stores object in Git like commits—better for releases
List with git show v1.0.0 shows message and commit

Tag a past commit:

bash

git tag -a v0.9.0 a1b2c3d -m "Beta snapshot"

List and Verify Tags

bash

git tag
git tag -l "v1.*"
git show v1.0.0

Checkout tag (detached HEAD—read-only inspection):

bash

git switch --detach v1.0.0

Create branch from tag if you need to patch old release:

bash

git switch -c hotfix/1.0.1 v1.0.0

Push Tags to Remote

Single tag:

bash

git push origin v1.0.0

All local tags:

bash

git push origin --tags

Code explanation:

git push alone does not push tags—must push explicitly
CI often triggers on tag push for release builds

Delete local tag:

bash

git tag -d v1.0.0

Delete remote tag:

bash

git push origin --delete v1.0.0

Semantic Versioning (SemVer)

Format: MAJOR.MINOR.PATCH

Bump	When
MAJOR	Breaking API change
MINOR	Backward-compatible feature
PATCH	Backward-compatible bug fix

Tag names usually prefixed:

text

v1.2.3
v2.0.0-beta.1

Align package versions in same release:

Stack	File	Example
npm / Node	`package.json` `"version"`	`"1.2.3"`
Maven	`pom.xml` `<version>`	`1.2.3`
Gradle	`build.gradle` `version`	`1.2.3`

See Maven, Gradle, and JavaScript tracks.

Workflow:

Bump version in project file
Commit: chore: release v1.2.3
Tag: git tag -a v1.2.3 -m "Release 1.2.3"
Push branch and tag

GitHub Releases (Concept)

On GitHub:

Releases → Draft a new release
Choose tag v1.0.0 or create on publish
Title, release notes, attach binaries (JAR, zip, installer)

Code explanation:

Release is platform UI around a tag—changelog for users
CI can upload artifacts when tag is pushed

Maintain CHANGELOG.md at repo root:

markdown

## [1.0.0] - 2026-05-28
### Added
- Initial public API

Link entries to compare views: v0.9.0...v1.0.0.

FAQ

Tag vs branch?

Branch moves with commits; tag is fixed bookmark.

Forgot to tag release commit?

Tag that SHA retroactively—document in CHANGELOG.

Lightweight tag on team repo?

Prefer annotated tags for audit trail.

npm version vs git tag?

Keep them in sync manually or use release tooling (npm version patch creates commit + tag).

Signed tags?

git tag -s v1.0.0 -m "Signed release"—requires GPG setup; optional for learning repos.

Clone specific version?

git clone then git switch v1.0.0 or shallow fetch single tag—advanced deploy pattern.