In GitHub, how do you control what automatically generated release notes contain?

## What generation actually reads GitHub builds notes from the **pull requests merged between two tags** — the previous release and the one being created. Each line is a pull request *title*, its number, and its author. Commits merged directly to the branch without a pull request do not appear, and neither do commit message bodies. That single fact reframes the whole feature: the changelog is assembled from metadata that reviewers already curate, so the way to improve it is to improve pull-request titles rather than to write notes by hand afterwards. The previous release is chosen automatically, and can be overridden — `previous_tag_name` on the API, `--notes-start-tag` on the CLI. That override is what makes generation usable on a maintenance branch, where "the previous release" chronologically is a newer major that has nothing to do with your line. ## Turning it on - API: `POST /repos/{owner}/{repo}/releases` with `"generate_release_notes": true`, which fills `body` for you. Anything you pass in `body` is kept and the generated content is appended. - CLI: `gh release create v2.5.0 --generate-notes`, or `--notes-file` to supply your own. - Preview without side effects: `POST /repos/{owner}/{repo}/releases/generate-notes` returns the name and body it *would* produce, given `tag_name` and optionally `previous_tag_name` and `configuration_file_path`. The preview endpoint is underused and genuinely handy — it lets a workflow post the proposed notes on a release-prep pull request before anything is published. ## Shaping with .github/release.yml The configuration file lives at `.github/release.yml` on the default branch, under a single `changelog:` key: - **`exclude.labels`** — pull requests carrying any of these labels are dropped entirely. The standard use is `ignore-for-release` for chores and internal refactors. - **`exclude.authors`** — drop by author, most often a bot account so that dependency-bump noise does not swamp the human changes. - **`categories`** — an ordered list. Each entry has a `title` (the heading rendered in the notes), a `labels` list that routes matching pull requests into it, and optionally its own `exclude`. Order matters: the first matching category wins, so put narrow categories such as *Breaking changes* above broad ones. - **A catch-all** — a final category whose `labels` is `['*']` collects everything unmatched, so nothing silently vanishes. Omit it and unlabelled pull requests disappear from the notes without warning, which is a quiet way to lose a change from the record. Because routing is label-driven, categories only work if labelling is real. Pair the file with a labelling habit enforced at review time, or accept that most entries land in the catch-all. ## What GitHub adds on its own Generated notes include a **New contributors** section crediting first-time merged authors, and a **Full changelog** link comparing the previous tag to this one. Both come free and both are the sort of thing hand-written notes forget. ## Generated versus hand-written The honest position is that generated notes are a *complete inventory* and a good changelog is a *narrative*. Inventory answers "what changed"; narrative answers "should I upgrade, and what will hurt". The pattern that works is to let generation produce the inventory and hand-write a short lead paragraph above it — breaking changes, migration steps, the one bug everybody hit. Passing `body` alongside `generate_release_notes: true` does exactly that: your prose first, the generated list beneath it. ## Failure modes worth naming - **Squash-merge titles become changelog lines.** If your squash commit title defaults to the pull request title, sloppy titles are permanent. Reviewers should fix the title before merging, not after. - **A missing catch-all category** silently drops unlabelled work. - **The wrong previous tag** on a maintenance release produces a changelog spanning an unrelated major. Set it explicitly on release branches. - **`release.yml` on a feature branch** does nothing; it is read from the default branch.