gh-release

List releases in a GitHub repository, limited to 30 items

$ gh release list

$ gh release view [tag]

$ gh release create [tag]

$ gh release delete [tag]

$ gh release download [tag]

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

gh release <command> [flags]

Common commands include:
gh release create <tag-name> [...] [flags]
gh release list [flags]
gh release view [<tag-name> | <id>] [flags]
gh release edit <tag-name> [flags]
gh release delete <tag-name> [flags]
gh release download [<tag-name>] [flags]

--repo <[HOST/]OWNER/REPO>
    Specify the repository to operate on, e.g., owner/repo-name.

--help
    Display help information for the specific command or subcommand.

-t, --title
    Set the title of the release (used with create or edit).

-n, --notes
    Provide release notes directly as a string (used with create or edit).

-F, --notes-file
    Read release notes from the specified file (used with create or edit).

-d, --draft
    Create or modify a release as a draft (not yet published).

-p, --prerelease
    Mark the release as a pre-release.

--generate-notes
    Automatically generate release notes from Git history (used with create).

--target
    Specify the target branch or commit for the release tag (used with create).

-L, --limit
    Limit the number of results returned (e.g., for list or download).

-D, --dir
    Specify the directory for downloading release assets (used with download).

--clobber
    Overwrite existing files when downloading assets (used with download).

The gh-release functionality, typically accessed via the gh release subcommand of the GitHub CLI, is a powerful tool designed to streamline the management of GitHub releases directly from your command line. It provides a comprehensive set of functionalities for interacting with releases on your GitHub repositories.

Users can effortlessly create new releases, defining their tag names, release titles, and descriptions, and attach various assets like binaries or archives. Beyond creation, it allows for viewing details of existing releases, listing all releases for a repository, editing release information, and deleting releases when necessary. Furthermore, it facilitates downloading release assets, making it easy to fetch compiled binaries or other artifacts.

This command is an essential tool for developers and CI/CD pipelines, integrating release management directly into the development workflow without needing to navigate the GitHub web interface. It supports both public and private repositories, respecting user authentication and permissions.

Using gh release requires the GitHub CLI (gh) to be installed and properly authenticated with your GitHub account. Users must possess appropriate permissions on the target repository (e.g., write access) to create, edit, or delete releases. While gh release create can automatically create a tag if it doesn't exist, it is generally recommended to create the Git tag beforehand using git tag for better control. Be aware of GitHub's limitations on asset sizes and total repository storage.

Before using any gh command, including gh release, you must authenticate your GitHub CLI instance by running gh auth login. This command links your CLI to your GitHub account, granting it the necessary permissions to manage repositories and releases securely.

When creating a new release, you can specify one or more files to upload as release assets by appending their paths to the gh release create command. For example: gh release create v1.0.0 ./my-app.tar.gz ./checksums.txt. Multiple assets can be added in a single command.

The GitHub CLI (gh), which provides the release subcommand, was first announced in 2019 and officially released in beta in early 2020. The gh release functionality was a core component of its initial feature set, recognizing the growing need for programmatic release management within development workflows and CI/CD pipelines. It aimed to provide a user-friendly and consistent interface for interacting with GitHub's powerful API directly from the terminal, abstracting away the complexities of HTTP requests and JSON parsing. Its ongoing development focuses on enhancing ease of use, adding more granular control over release properties, and supporting comprehensive asset management, making it an indispensable tool for automated software delivery on GitHub.

gh(1), git(1), curl(1)