ghcli / Releases & Gists / gh release create

gh release create

Tag, note, and ship a release

gh release create publishes a GitHub release from your terminal. It creates the tag, attaches build artifacts, and can auto-generate release notes from merged pull requests — perfect for the final step of a CI pipeline.

Quick answer

gh release create v1.0.0 --generate-notes

↧ Download snippet Full cheat sheet

Syntax

gh release create <tag> [<files>...] [flags]

Examples

Create a release with auto-generated notes

gh release create v1.0.0 --generate-notes

Attach built binaries

gh release create v1.0.0 ./dist/app-linux ./dist/app-macos

Title and notes from a file

gh release create v1.0.0 --title "1.0.0" --notes-file CHANGELOG.md

Publish a prerelease

gh release create v1.1.0-beta --prerelease --generate-notes

Create a draft to edit before publishing

gh release create v1.0.0 --draft --generate-notes

Options & flags

Flag	What it does
-t, --title	Release title.
-n, --notes	Release notes text.
-F, --notes-file	Read release notes from a file (- for stdin).
--generate-notes	Automatically generate notes from merged PRs.
-d, --draft	Save as a draft instead of publishing.
-p, --prerelease	Mark the release as a prerelease.
--target	Target branch or full commit SHA for the tag.
--latest	Explicitly mark (or not) this as the latest release.

How to use gh release create, step by step

Decide the version tag, e.g. v1.0.0.
Build your artifacts so you can attach them.
Run gh release create v1.0.0 ./dist/* --generate-notes.
Verify the published release with gh release view v1.0.0.

Common errors and fixes

a release with the same tag name already exists

Pick a new tag, or update the existing release with gh release edit / upload files with gh release upload.

tag_name is not a valid tag

Provide a valid tag string. gh will create the tag if it doesn't exist; use --target to point it at a branch or SHA.

Related commands

Frequently asked questions

How do I create a GitHub release from the command line?

Run gh release create <tag>, e.g. gh release create v1.0.0 --generate-notes. Add file paths to attach binaries and --generate-notes to build the changelog from merged PRs.

How do I attach binaries to a release?

List the file paths after the tag: gh release create v1.0.0 ./dist/app-linux ./dist/app-macos. Each file is uploaded as a downloadable asset.

Can I create a draft or prerelease?

Yes. Use --draft to publish later, or --prerelease to mark it as a preview build.