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: 
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.
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."
FlagDescriptionExample
—titleSets the release title--title "Initial Release"
—notesSupplies the body of the release notes--notes "Bug fixes and performance updates"
—draftMarks the release as a draft--draft
—prereleaseDesignates the release as a pre-release--prerelease
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 SegmentWhen to IncrementExample Change
MAJORIncompatible API changes1.0.0 → 2.0.0
MINORBackwards-compatible functionality additions1.1.0 → 1.2.0
PATCHBackwards-compatible bug fixes and performance tweaks1.0.0 → 1.0.1
Refer to the SemVer specification for detailed guidelines on version numbering.

​
4. Example Workflow

  1. Commit your changes: 
    git add .
git commit -m "Implement user login feature"
  2. 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."
  3. Verify on GitHub under Releases to confirm the entry and assets.

Watch Video