# GitHub release notes template, with live example

> **TL;DR** GitHub release notes live in each Release's description, so a template is a Markdown skeleton you paste there, plus an optional .github/release.yml that groups merged pull requests under headings. This guide has both to copy. GitHub's Releases list is a feed, not a page you can brand or link feedback to. To publish the same notes as a changelog page that also cites the requests each release shipped, open your repository as a Gitback Board.

GitHub keeps release notes in the description of each Release, so a template is a Markdown skeleton you paste into that field, and the part you can automate is the list of merged pull requests. The Releases list on GitHub is a feed, and it is where most projects stop.

## What should a GitHub release notes template contain?

A release notes template should say what changed for the user, in a fixed order, so readers can scan a release in seconds. Paste this into the description of a new release and replace the bracketed parts.

```markdown
## Highlights
- **[Feature name].** [One sentence on what a user can now do.] ([#NUMBER](https://github.com/OWNER/REPO/pull/NUMBER))

## Fixes
- [What was broken and is now fixed.] ([#NUMBER](https://github.com/OWNER/REPO/pull/NUMBER))

## Upgrade notes
- [Anything a user must do or know before updating, or "None".]

## Full changelog
https://github.com/OWNER/REPO/compare/vPREVIOUS...vTHIS
```

Highlights come first because most readers stop there. Keep Upgrade notes even when it says "None", so a reader who looks for breaking changes can see you checked.

## How do you generate GitHub release notes automatically?

You draft a new release and click **Generate release notes**. GitHub's documentation says the generated notes include a list of merged pull requests, a list of contributors to the release and a link to the full changelog.

1. On the repository's main page, click **Releases**, then **Draft a new release**.
2. Choose a tag, or type a new version number and click **Create new tag**.
3. Optionally pick the previous tag, so GitHub knows where this release's range starts.
4. Type a release title and click **Generate release notes**.
5. Read the generated notes and edit them, then click **Publish release**, or **Save draft** to finish later.

GitHub also lets you create a Discussion for the release if Discussions is on, by ticking **Create a discussion for this release** and choosing a category.

## How do you group release notes with a release.yml file?

Create `.github/release.yml` and list your categories by pull request label. The file is read when GitHub generates notes, so the headings appear without any editing. `changelog.categories` takes a `title` and a list of `labels` for each category, `*` catches pull requests that matched none of the earlier ones, and `changelog.exclude` leaves out labels and authors.

```yaml
changelog:
  exclude:
    labels:
      - ignore-for-release
  categories:
    - title: New features
      labels:
        - enhancement
    - title: Bug fixes
      labels:
        - bug
    - title: Everything else
      labels:
        - "*"
```

This groups pull requests, which means your labels have to be on them. A pull request without a label lands in the catch-all, so keep `*` last.

## How do you create release notes from the command line?

Pass `--generate-notes` to `gh release create`, and the GitHub CLI asks GitHub's release notes API to write the notes. To use your own text instead, point `--notes-file` at a file you wrote from the template above, and add `--draft` to save the release without publishing it.

```bash
gh release create v1.4.0 --title "v1.4.0" --generate-notes
gh release create v1.4.0 --title "v1.4.0" --notes-file RELEASE_NOTES.md --draft
```

The first command publishes straight away, so run it from a release workflow you trust, or add `--draft` and read the notes first.

## How do you write release notes that people read?

Write each line for the person updating, not for the person who merged the change. A pull request title such as "Refactor cache layer" tells a user nothing, while "Pages load faster after the first visit" does, and the pull request link beside it gives a maintainer the detail. Three habits keep notes readable:

- **One sentence per change.** If a change needs a paragraph, link a doc and keep the line short.
- **Name what a user must do.** A breaking change or a required setting goes under Upgrade notes, not buried in Fixes.
- **Credit the request.** If a user asked for the feature, say so and link their issue or Discussion. They get told it shipped, and other users see that asking works.

Generated notes are a good first draft because they never miss a merged pull request, and a poor final draft because pull request titles are written for reviewers. Edit them before you publish.

## Should you use GitHub Releases or a CHANGELOG.md file?

Use Releases if you ship versions people download or watch, and a `CHANGELOG.md` if you want the history to travel with the code. A Release is attached to a tag, can carry binary files, and can notify people who watch the repository, which is also why publishing one is not something to do by accident. A `CHANGELOG.md` is an ordinary file, so it is versioned, reviewed in pull requests and read by anyone who clones the repository, but it notifies no one. Many projects keep both and paste the same text into each. The Releases route is the one a tool can read through GitHub's API, and it is the one a changelog page can be built from.

## What does a finished release notes page look like?

Gitsu's changelog, at [gitback.us/b/sahildave/gitsu/changelog](/b/sahildave/gitsu/changelog), is a live example built from the Releases of its GitHub repository.

![Gitsu's changelog page on Gitback showing the v0.10.0 release dated November 7, 2026, with Highlights, a collapsed Full changelog, Installation and Auto-updates sections, then a Shipped from your feedback list with vote counts](/content/github-release-notes-template/gitsu-changelog-board.png)

The release has the shape this guide recommends: Highlights first, a collapsed Full changelog, then Installation and Auto-updates sections that suit a desktop app. Below the notes is a list headed "Shipped from your feedback", with each shipped request and its vote count. Nothing on the page was written for Gitback. It is the Release's own body.

## How do you turn GitHub Releases into a public changelog page?

You open the repository as a Gitback Board, and its Changelog Module reads the Releases. The module takes the repository's newest 30 published Releases, newest first, and renders each Release's whole body as Markdown, so a template like the one above shows up as written. Drafts are not shown.

The module does one thing GitHub's Releases list does not. Each entry cites the requests the release shipped, with their vote counts, drawn from the roadmap items marked complete. A Client, meaning a GitHub account with write access, is offered a confirmed comment on the originating Discussion when an item ships, and GitHub's own notifications then reach everyone who asked. The comment is shown to the Client before it sends and is posted under their own token.

1. Open the repository's Board from [Open a Board](/b) by pasting its URL.
2. Claim it by signing in with a GitHub account that has write access. [Open a Gitback Board for your repo and claim it](/docs/getting-started) has the steps.
3. Publish a Release on GitHub as usual. Gitback's [Changelog Module](/features/changelog) shows it on the Board.

## What does the Changelog Module not do?

It reads Releases and nothing more. These limits come from the product's rules and code:

- **It never publishes a Release.** Gitback does not create, edit or publish one. Releases notify watchers and can trigger CI, and a release-notes editor would compete with GitHub's own. It can generate notes for a Client to copy, which the Client then publishes on GitHub.
- **It shows the newest 30.** An older Release stays on GitHub but not on the Board.
- **It hides drafts.** A Release with no publish date is not shown.
- **It does not write notes for you.** The Board's text is your Release body, so a thin body gives a thin page.

Open-source repositories are free on every Plan; private Boards and custom domains are on the [pricing page](/pricing). The roadmap that feeds the shipped list is covered in [GitHub public roadmap for a repo](/guides/github-public-roadmap), and more guides are in [Guides](/guides).

## Frequently asked questions

### How do I write good GitHub release notes?

Lead with what changed for the user, group changes under a few fixed headings, and link each line to its pull request or issue. The template in this guide uses Highlights, Fixes and Upgrade notes, and GitHub's Generate release notes button fills in the merged pull requests and contributors for you.

### How do I generate release notes automatically on GitHub?

When you draft a new release, click Generate release notes. GitHub adds a list of merged pull requests, the contributors to the release and a link to the full changelog. To group them under your own headings, add a .github/release.yml that lists categories by pull request label.

### Where is the .github/release.yml file for release notes?

At .github/release.yml in the repository, on the default branch. It takes changelog.categories, each with a title and a list of labels, and changelog.exclude for labels and authors to leave out.

### Does GitHub have a release notes page?

GitHub shows each Release on the repository's Releases page, which is a feed of releases and drafts. It does not give you a separate branded changelog page. A tool such as Gitback can read those Releases and show them as one.

### Does Gitback write or publish GitHub Releases?

No. The Changelog Module only reads a repository's Releases. It never creates, edits or publishes one, because publishing a Release can notify watchers and trigger CI.