Skip to main content
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:
Example:
This creates both the v1.0.0 Git tag and the GitHub Release entry.
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:
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:
Refer to the SemVer specification for detailed guidelines on version numbering.

​
4. Example Workflow

  1. Commit your changes:
  2. Create and push a new tag with Release:
  3. Verify on GitHub under Releases to confirm the entry and assets.

Watch Video