To configure GitHub’s generated release notes, first apply consistent labels to pull requests before they merge, then add a .github/release.yml file that maps those labels to reader-friendly categories. When you create a draft release, choose Generate release notes and GitHub will group the merged pull requests according to that configuration. Treat the result as a draft: check breaking changes, migration instructions, and anything that should not be announced before you publish.
Start with labels your team can use consistently
Generated notes can only be as clear as the labels behind them. Before writing configuration, look at the labels already used on merged pull requests. A small set is easier to apply accurately than a catalog of clever but overlapping names.
For many projects, three visible categories are enough:
featurefor a new capability readers can usebugfor a user-facing correctiondocumentationfor guides, examples, or docs-only changes
Your exact label names do not matter; the names in release.yml simply need to match the labels in the repository. Labels such as needs review, internal, or priority: high are useful for team coordination but usually make poor release-note headings. A release note should answer the reader’s question: what changed for me?
Decide who applies labels and when. Some teams add them when a pull request is opened; others require an author or reviewer to add a final label before merging. Either approach works when it is part of the normal pull-request checklist. If labels are applied only after a release is drafted, the configuration will be technically correct but the output will still be a messy catch-all list.
Add a small release-note configuration
Create .github/release.yml on the default branch. This example groups the three labels above and gives uncategorized pull requests a useful home:
changelog:
categories:
- title: Features
labels:
- feature
- title: Fixes
labels:
- bug
- title: Documentation
labels:
- documentation
- title: Other changes
labels:
- "*"
The final "*" category is important. It catches pull requests without one of the earlier labels, so an operational change or maintenance improvement does not disappear from the draft. Put it last: GitHub uses the first matching category, so a broadly matching category placed first would swallow the more meaningful groups.
Keep headings short and written for the people who read releases, not the people who administer labels. If an API has a distinct audience, a category such as API changes may make sense. Do not create one category for every internal component unless release readers truly need that detail. GitHub’s official generated release notes documentation explains the current configuration options, including exclusions and contributor settings.
Make a draft release and generate the notes
Once the configuration is in the repository, open the project’s Releases page and choose Draft a new release. Select the tag you intend to publish, enter a title that matches the release, then use Generate release notes. GitHub compares the selected tag with the previous release and builds a draft from the relevant merged pull requests, contributors, and a link to the full changelog.
Do this in a draft rather than publishing immediately. It gives you room to see whether a pull request was labeled as expected and whether the chosen tag compares the right range of changes. If the category layout looks wrong, check the pull request labels first, then check spelling and indentation in .github/release.yml. A configuration change affects future generated drafts; it does not relabel an old pull request for you.
Generated release notes do not choose a version number or decide what your compatibility policy should be. Pick the tag and release version using your project’s own process. GitHub’s about releases guide is a helpful reference for tags, drafts, and published releases.
Review the draft like a real release artifact
Automation saves formatting time, but it cannot judge context. Read the generated note before publishing and make four deliberate checks.
First, call out breaking changes and migration steps near the top. A label called feature may contain a renamed setting, removed endpoint, or changed default that users need to act on. Add a short, plain-language explanation and link to the relevant documentation.
Second, verify sensitive or incomplete work is not included. An accidentally merged experiment, a private issue reference, or a change that has not shipped in the selected build may need to be removed from the release note while the team investigates the underlying process. Do not rely on a release edit to hide a security problem; follow your project’s responsible disclosure and security-response process.
Third, check the wording of pull-request titles. A title written for a code review may be too vague for a customer. It is fine to rewrite a line in the release note so readers understand the outcome, while keeping the pull request link for technical detail. Finally, scan contributor attribution and the full-changelog range. Correct credit and a correct comparison link help readers trace a change without turning the note into a commit dump.
If your repository already requires review before merging, retain that control for this configuration file as well. Our guide to requiring one pull request review before merging can help protect release-process changes from a quick, unreviewed edit.
Test with one low-risk release first
You do not need a major launch to validate the workflow. For the next small release, make sure one merged pull request has each expected label and leave one harmless maintenance pull request unlabeled. Create a draft, generate the notes, and confirm that each appears once in the intended heading and that the unlabeled item lands in Other changes.
Use the test to agree on ambiguous cases. For example, a feature that also fixes a bug should usually get the label that best describes its main reader-visible result, rather than every possible label. A predictable convention produces better notes than a complicated configuration trying to infer intent after the fact.
Release notes work best alongside a dependable pull-request workflow. Before you make every label change urgent, make sure contributors can see basic test results; our walkthrough for running Node.js tests on every GitHub pull request shows one practical starting point. Then revisit your categories after a few releases. If readers skim past a category or contributors rarely use a label, simplify it. The goal is a draft that needs a thoughtful review, not a draft that needs to be rebuilt from scratch.
Official sources
- GitHub Docs: Automatically generated release notes
- GitHub Docs: About releases