gh release create Command Reference

Cut a GitHub release and attach your build artifacts.

gh release create publishes a release for a tag and uploads assets. It is the release step at the end of a build pipeline.

What it does

gh release create publishes a release tied to a git tag, with a title and notes, and uploads asset files passed as positional arguments. It can auto-generate notes from merged PRs and mark a release as prerelease or draft.

Common flags and usage

TAG [files...]: the tag and any asset files to attach
--title / --notes / --notes-file: release title and body
--generate-notes: auto-generate notes from merged PRs
--prerelease / --draft: mark the release accordingly
--target BRANCH: commitish the tag points at if it does not exist yet

Example

shell

- name: Publish release
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    gh release create "${{ github.ref_name }}" dist/*.tar.gz \
      --title "${{ github.ref_name }}" --generate-notes

In CI

Run this on a tag push and pass artifact globs as positional arguments to upload them. --generate-notes saves writing changelogs by hand. Set GH_TOKEN so the release is authenticated.

Key takeaways

Positional file arguments are uploaded as release assets.
--generate-notes builds release notes from merged PRs automatically.
Trigger on tag pushes and authenticate with GH_TOKEN.