Organizing Your Repository Using Git Tags in GitHub Releases

GitHub Releases provide official, versioned snapshots of your codebase. Each Release is backed by a Git tag, marking a precise point in your commit history. Leveraging Releases and tags helps you:

Clearly identify versions (e.g., v1.0.0, v2.1.3)
Distribute binaries and assets
Publish detailed release notes and changelogs

The image explains the concepts of releases and tags in GitHub, highlighting that releases are official snapshots tied to version numbers, based on Git tags, which help organize and track code changes.

Prerequisites

GitHub CLI (gh) installed and authenticated (gh auth login).
A Git repository with commits you want to release.

1. Creating a Release Tag with GitHub CLI

Use the gh release create command to generate a Git tag and corresponding GitHub Release.

Basic syntax:

gh release create <tag-name>

Example:

gh release create v1.0.0

This creates both the v1.0.0 Git tag and the GitHub Release entry.

Note

If this is your first time using the GitHub CLI, run gh auth login to authenticate.

1.1 Adding a Title and Release Notes

To provide context, include a title and detailed notes:

gh release create v1.0.0 \
  --title "Initial Release" \
  --notes "Features: user authentication, API endpoints, UI enhancements."

Flag	Description	Example
--title	Sets the release title	`--title "Initial Release"`
--notes	Supplies the body of the release notes	`--notes "Bug fixes and performance updates"`
--draft	Marks the release as a draft	`--draft`
--prerelease	Designates the release as a pre-release	`--prerelease`

Warning

Once a tag is published as a public Release, avoid rewriting or deleting it—immutable tags preserve release integrity.

2. Understanding Semantic Versioning

Semantic Versioning (SemVer) is a widely adopted specification for version numbers in the form MAJOR.MINOR.PATCH. It clarifies how version numbers change with each type of update:

Version Segment	When to Increment	Example Change
MAJOR	Incompatible API changes	1.0.0 → 2.0.0
MINOR	Backwards-compatible functionality additions	1.1.0 → 1.2.0
PATCH	Backwards-compatible bug fixes and performance tweaks	1.0.0 → 1.0.1

Note

Refer to the SemVer specification for detailed guidelines on version numbering.

3. Links and References

4. Example Workflow

Commit your changes:

git add .
git commit -m "Implement user login feature"

Create and push a new tag with Release:

gh release create v1.1.0 \
  --title "Login Feature Release" \
  --notes "Added OAuth2-based login, session management."

Verify on GitHub under Releases to confirm the entry and assets.

Watch Video

Watch video content