gh release create: Usage, Options & Common CI Errors

Cut a tagged GitHub release - with notes and asset uploads - from CI.

gh release create creates a release for a tag, attaching binaries and either custom or auto-generated notes. It is the standard last step of a release pipeline.

What it does

gh release create <tag> creates (and optionally tags) a GitHub release. You can attach asset files inline, set the title and notes (or --generate-notes to derive them from merged PRs), and mark it as a prerelease or draft. It creates the git tag if it does not already exist.

Common usage

# Create a release and attach assets, auto-generating notes
gh release create v1.2.0 ./dist/*.tar.gz --generate-notes

# Explicit title and notes from a file
gh release create v1.2.0 --title "v1.2.0" --notes-file CHANGELOG.md

# Prerelease, targeting a specific commit
gh release create v1.3.0-rc.1 --prerelease --target "$GITHUB_SHA"

Common error in CI: tag already exists / missing notes

gh release create fails with "a release with the same tag name already exists" when the tag was released before, or prompts for notes in a non-TTY. Fix: use a unique, not-yet-released tag (or gh release delete/gh release edit to update an existing one), and always provide notes non-interactively via --notes, --notes-file, or --generate-notes. The token needs repo scope (contents: write permission) to create releases and tags.

Key options

Related guides