Releases — Understanding GitHub CLI

The gh release command lets you create, manage, and distribute software releases directly from the terminal.

Creating a Release

# Interactive
gh release create v1.0.0
 
# From a specific branch or commit
gh release create v1.0.0 --target main
 
# With title and notes
gh release create v1.0.0 --title "Version 1.0.0" --notes "First stable release"
 
# Generate release notes automatically from merged PRs
gh release create v1.0.0 --generate-notes
 
# Draft release (not published yet)
gh release create v1.0.0 --draft
 
# Pre-release
gh release create v2.0.0-beta.1 --prerelease
 
# Upload assets during creation
gh release create v1.0.0 ./dist/app-linux-amd64 ./dist/app-darwin-amd64 ./dist/app-windows-amd64.exe
 
# Notes from a file
gh release create v1.0.0 --notes-file CHANGELOG.md

Auto-Generated Release Notes

GitHub can automatically generate notes from the PRs merged since the last release:

gh release create v1.2.0 --generate-notes --notes-start-tag v1.1.0

Listing Releases

gh release list
 
# Limit results
gh release list --limit 10
 
# Exclude drafts and pre-releases
gh release list --exclude-drafts --exclude-pre-releases
 
# JSON output
gh release list --json tagName,publishedAt,isPrerelease

Viewing a Release

# View in terminal
gh release view v1.0.0
 
# Open in browser
gh release view v1.0.0 --web
 
# View the latest release
gh release view --json tagName,body

Editing a Release

gh release edit v1.0.0 --title "Updated Title"
gh release edit v1.0.0 --notes "Updated release notes"
gh release edit v1.0.0 --draft=false     # Publish a draft
gh release edit v1.0.0 --prerelease=false # Remove pre-release flag
gh release edit v1.0.0 --latest          # Mark as latest

Downloading Release Assets

# Download all assets from a release
gh release download v1.0.0
 
# Download to a specific directory
gh release download v1.0.0 --dir ./downloads
 
# Download a specific asset by pattern
gh release download v1.0.0 --pattern "*.tar.gz"
 
# Download from the latest release
gh release download --pattern "*.deb"
 
# Download from a different repo
gh release download v1.0.0 -R cli/cli --pattern "*linux*amd64*"

Uploading Additional Assets

gh release upload v1.0.0 ./dist/new-binary --clobber

The --clobber flag overwrites an existing asset with the same name.

Deleting a Release

gh release delete v1.0.0 --yes
 
# Also delete the associated Git tag
gh release delete v1.0.0 --yes --cleanup-tag

Deleting a Specific Asset

gh release delete-asset v1.0.0 app-linux-amd64 --yes

Verifying Releases (Attestations)

If the project uses artifact attestations (cryptographic proof of build provenance):

# Verify the entire release has valid attestations
gh release verify v1.0.0
 
# Verify a specific downloaded asset against the release
gh release verify-asset v1.0.0 ./downloaded-binary
 
# JSON output for automation
gh release verify v1.0.0 --json

This validates that release artifacts were built from the expected source in the expected CI environment using SLSA provenance.

A Release Workflow Example

# 1. Tag the release
git tag v1.2.0
git push origin v1.2.0
 
# 2. Build your binaries
make build-all   # hypothetical build step
 
# 3. Create the release with auto-generated notes and assets
gh release create v1.2.0 \
  --title "v1.2.0" \
  --generate-notes \
  ./dist/app-linux-amd64 \
  ./dist/app-darwin-amd64 \
  ./dist/app-windows-amd64.exe
 
# 4. Verify it
gh release view v1.2.0 --web

Exercises

Create a test tag: git tag v0.0.1 && git push origin v0.0.1
Create a release: gh release create v0.0.1 --title "Test" --notes "Testing releases"
List releases: gh release list
View it: gh release view v0.0.1
Delete it: gh release delete v0.0.1 --yes --cleanup-tag