Drafts your next release notes as pull requests are merged into master.

Usage

You can use the Release Drafter GitHub Action in a GitHub Actions Workflow by configuring a YAML-based workflow file, e.g. .github/workflows/release-drafter.yml, with the following:

name: Release Drafter

on:
  push:
    branches:
      - main
      - master

# Permissions for default token (secrets.GITHUB_TOKEN)
permissions:
  contents: write
  pull-requests: read

jobs:
  update_release_draft:
    runs-on: ubuntu-latest
    steps:
      - uses: release-drafter/release-drafter@v7
        with:
          config-name: release-drafter.yml # the default, loads '.github/release-drafter.yml'

Configuration

The action requires a configuration file. Default location is .github/release-drafter.yml, and will be fetched using octokit behind the scenes. You do not need to checkout your repository beforehand.

[!note]
For advanced scenarios, please read dedicated Configuration Loading article. (ex: dynamic config, extending other files, fetch from another repo, etc...)

Example

For example, take the following .github/release-drafter.yml file in a repository:

template: |
  ## What’s Changed

  $CHANGES

As pull requests are merged, a draft release is kept up-to-date listing the changes, ready to publish when you’re ready:

The following is a more complicated configuration, which categorises the changes into headings, and automatically suggests the next version number:

name-template: "v$RESOLVED_VERSION 🌈"
tag-template: "v$RESOLVED_VERSION"
categories:
  - title: "🚀 Features"
    semver-increment: minor
    when:
      labels:
        - "feature"
        - "enhancement"
  - title: "🐛 Bug Fixes"
    when:
      labels:
        - "fix"
        - "bugfix"
        - "bug"
  - title: "🧰 Maintenance"
    when:
      label: "chore"
  - type: "pre-exclude"
    when:
      label: "skip-changelog"
  - type: "version-resolver"
    semver-increment: "major"
    when:
      label: "major"
  - type: "version-resolver"
    semver-increment: "patch"
change-template: "- $TITLE @$AUTHOR (#$NUMBER)"
change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
template: |
  ## Changes

  $CHANGES

Configuration Options

You can configure Release Drafter using the following key in your .github/release-drafter.yml file:

Template Variables

You can use any of the following variables in your template, header and footer:

Category Template Variables

You can use any of the following variables in category-template:

Next Version Variables

You can use any of the following variables in your template, header, footer, name-template and tag-template: