Blog

GitHub release notes automation: a step-by-step setup

You can automate release notes on GitHub by letting GitHub write a first draft from your merged pull requests every time you tag a release, and then editing that draft into something your readers can use. The automation removes the blank page. It does not remove the editing.

This guide shows the setup in three steps: generate notes on the release page, generate them from a workflow when you push a tag, and shape the output with a small configuration file. It also covers what the generated text does not do, so you know what is left for a person.

If you only need to turn a list of commits into a changelog entry once, the free changelog generator does it in your browser without a workflow.

Step 1: let GitHub generate the notes

When you draft a release in the GitHub interface, there is a button to generate release notes. GitHub fills the description with a list of the pull requests merged since the previous release, the people who contributed, and a link to the full changelog comparison. The GitHub documentation on automatically generated release notes describes the feature and its options.

The quality of this list follows the quality of your pull request titles. A title such as "Add PDF export to reports" reads well in a release. A title such as "fix stuff" does not.

Step 2: create the release from a workflow

To stop doing it by hand, create the release from a GitHub Actions workflow that runs when you push a version tag. The workflow below uses the GitHub command line tool, which can generate the notes for you with one flag:

name: Release
on:
  push:
    tags: ["v*"]
permissions:
  contents: write
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Create the release with generated notes
        env:
          GH_TOKEN: ${{ github.token }}
        run: gh release create "${{ github.ref_name }}" --generate-notes

The workflow needs permission to write repository contents, which is what the permissions block grants. Push a tag that starts with v, such as v1.4.0, and a release appears with its notes already filled in.

git loga3f9c21feat: add pdf export7be04d8fix: oauth redirect loop51c2e90chore: bump depse8d1b37feat: export button0f6a4c2fix: typo in settings92b7d15refactor: report service✦CHANGELOG.md## 1.2.0 - 2026-10-12### Added- Export reports to PDF### Fixed- Login redirect loop3 of 6 commits left out
A changelog keeps what readers can notice and drops the noise.

Step 3: group the notes with .github/release.yml

Without configuration, the generated list is flat. A file named .github/release.yml tells GitHub how to group pull requests by label and which ones to leave out:

changelog:
  exclude:
    labels:
      - ignore-for-release
  categories:
    - title: New features
      labels:
        - enhancement
    - title: Bug fixes
      labels:
        - bug
    - title: Other changes
      labels:
        - "*"

With this file, pull requests labelled enhancement go under "New features", bug under "Bug fixes", and anything labelled ignore-for-release is left out. The grouping only works if your team labels pull requests consistently, so decide the labels once and add a check to your pull request template.

What generated notes do not do

For a side-by-side view of GitHub's feature and a tool that writes the customer-facing version, see GitHub generated release notes vs ReleaseTale.

  • They list pull requests, not benefits. A user reading "Refactor report service" learns nothing about what changed for them.
  • They do not call out breaking changes unless someone labels or titles the pull request that way.
  • They are one document. Developers want a dated record of every change, and customers want a short explanation of what is new. One list rarely serves both.
  • They stay on the release page. A CHANGELOG.md file, a public changelog page or an in-app notice still needs its own copy.

Other tools approach the same problem from the commit side, for example by reading Conventional Commits to decide the next version. The comparison of release notes generators covers five approaches and what to check before you publish.

Turn the generated list into release notes people read

The practical workflow is to automate the first draft and keep a short human pass for the rest: reword each entry from the reader's point of view, move breaking changes to the top, and drop anything internal. The guide on how to write a changelog lists the habits to apply in that pass, and the Keep a Changelog template gives you the structure for the developer version.

If you would rather not do that pass from scratch, ReleaseTale reads the commits and pull requests of a release and drafts both versions, one for your users and one for developers. You edit them and publish to a hosted page, a What's new popup or a Markdown file. See the changelog examples to judge the output.

Frequently asked questions

How do I automate release notes on GitHub?

Create the release from a GitHub Actions workflow that runs when you push a version tag, and let the GitHub command line tool generate the notes with the generate-notes option. GitHub fills the release with the merged pull requests since the previous release.

Can GitHub generate release notes automatically?

Yes. GitHub can generate release notes from merged pull requests, listing the changes, the contributors and a link to the full comparison. You can group the list by label with a .github/release.yml file.

Are GitHub generated release notes enough for users?

Usually not on their own. They list pull request titles, so they read like a developer changelog. Most products edit them into plain-language notes and call out breaking changes.

Related articles