Getting started

1. Install

As a gh extension (recommended):

gh extension install specsnl/gh-release-changes
gh release-changes version

Or with Homebrew, which puts a standalone gh-release-changes binary on your PATH:

brew install specsnl/tap/gh-release-changes
gh-release-changes version

specsnl/tap/gh-release-changes@rc tracks the newest tag, release candidates included. gh does not treat the Homebrew binary as an extension, so Homebrew users run gh-release-changes … where these pages say gh release-changes ….

2. Authenticate

Authentication is gh’s own: gh auth login, GH_TOKEN, or GH_HOST for GitHub Enterprise. The tool never reads, stores or prints a token.

Reading the generated notes goes through POST /repos/{owner}/{repo}/releases/generate-notes, which GitHub guards with Contents: write even though it creates nothing. A user with read-only access to a repository cannot use the tool on it.

3. Render a release

gh release-changes sort v1.2.0            # grouped "What's Changed" Markdown
gh release-changes issues v1.2.0          # plain issue list per group
gh release-changes dump v1.2.0            # issue details to write release notes from
gh release-changes check-notes v1.2.0 --file notes.md
                                          # notes against the issues of the release
gh release-changes items v1.2.0 | jq .    # the JSON every other output is rendered from

Run it inside a clone of the repository, or pass -R owner/repo. Leave out the tag in a terminal to pick one from the repository’s tags — see Commands. The base of the comparison is GitHub’s choice — see Commands; --since-final compares a release candidate with the previous final release instead, so it covers the whole release cycle.