gh-release

List releases in a GitHub repository, limited to 30 items

$ gh release [[ls|list]]

$ gh release view [tag]

$ gh release [[new|create]] [tag]

$ gh release delete [tag]

$ gh release download [tag]

$ gh release upload [tag] [path/to/file1 path/to/file2 ...]

gh release [-R OWNER/REPO] <command> [<args>...] [--flags]

--repo OWNER/REPO, -R OWNER/REPO
    Operate on a specific GitHub repository

--help, -h
    Show help for release command

create [TAG] [flags]
    Create a new release (draft or published)

delete RELEASE
    Delete a release and its Git tag

download [RELEASE]
    Download assets from a release

edit [RELEASE] [flags]
    Edit an existing release

list [flags]
    List releases for the repository

notes [TAG]
    Regenerate or view release notes

upload RELEASE [flags]
    Upload assets to a release

view [RELEASE] [flags]
    View details of a specific release

gh release is a powerful subcommand of the GitHub CLI (gh) for handling GitHub repository releases directly in the terminal. It enables creating new releases from tags, listing all releases, viewing detailed information, editing existing releases, deleting them, uploading binary assets, downloading release assets, and even generating release notes from commit messages.

This tool integrates with GitHub's REST API, requiring prior authentication via gh auth login. It supports both personal and organization repositories, with options to target specific repos using the --repo flag. Ideal for CI/CD pipelines, it automates release workflows, supports draft and pre-releases, and handles large assets efficiently.

Key benefits include speed, scriptability, and native GitHub integration without needing personal access tokens manually. It's cross-platform (Linux, macOS, Windows) and outputs in human-readable or JSON formats for parsing.

Requires GitHub CLI installed and authenticated account. Some operations need write permissions on the repository. Assets larger than 2GB may have limitations.

Install via sudo apt install gh (Debian/Ubuntu), brew install gh (macOS), or binaries from GitHub releases.
Authenticate: gh auth login.

gh release create v1.0.0 ./bin/* --title "v1.0.0" --notes-from conventional-commits
Creates release from tag with assets and auto-generated notes.

Use --jq flag on list/view: gh release list --jq '.[] | .tag_name' for parsing.

Introduced in GitHub CLI v0.5.0 (February 2020). Actively developed by GitHub; current stable v2.48.0 (2024) adds JSON output, improved notes generation.

gh(1), git-tag(1)