Draft the next release notes as pull requests merge into a branch.

Usage

Add the Release Drafter GitHub Action to a GitHub Actions workflow. For example, create .github/workflows/release-drafter.yml with this content:

name: Release Drafter

on:
  push:
    branches:
      - main

# Permissions for the default token.
permissions:
  contents: write
  pull-requests: read

jobs:
  update_release_draft:
    runs-on: ubuntu-slim
    steps:
      - uses: release-drafter/release-drafter@v7
        with:
          # This default loads .github/release-drafter.yml.
          config-name: release-drafter.yml

Command-line interface

Release Drafter provides a CLI for local use and automation. The CLI requires Node.js 24 or later.

npx release-drafter owner/repo --dry-run

For GitHub.com or GitHub Enterprise Cloud on *.ghe.com, authenticate with GH_TOKEN or GITHUB_TOKEN. For GitHub Enterprise Server, use GH_ENTERPRISE_TOKEN or GITHUB_ENTERPRISE_TOKEN. Release Drafter does not invoke gh. To use GitHub CLI credentials, pass them through GH_TOKEN:

GH_TOKEN="$(gh auth token)" npx release-drafter owner/repo --dry-run

The CLI can validate one pull request with the same category rules as the Check PR action:

npx release-drafter check-pr owner/repo 123

See the release-drafter package README for installation instructions, the complete option reference, configuration targets, JSON output, and exit codes.

Check pull requests

The read-only Check PR action validates a pull request against the title or label conditions in Release Drafter categories. See check-pr/README.md for the workflow, permissions, supported events, and matching behavior.

Configuration

The action requires a configuration file. By default, it loads .github/release-drafter.yml through the GitHub API. You do not need to check out the repository.

Example

Create .github/release-drafter.yml with this content:

template: |
  ## What's Changed

  $CHANGES

When a pull request merges, Release Drafter adds the change to a draft release:

This example groups changes and calculates 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 (#$NUMBER) $AUTHORS'
# Add # and @ to prevent mentions. Add ` to prevent code blocks.
change-title-escapes: '\<*_&'
template: |
  ## Changes

  $CHANGES

Configuration options

The .github/release-drafter.yml file supports these keys:

Template variables

Use these variables in template, header, and footer:

Category template variables

Use these variables in category-template:

Next version variables

Use these variables in template, header, footer, name-template, and tag-template:

Next version component helpers

Each $NEXT_{MAJOR,MINOR,PATCH}_VERSION variable has component variables:

Version template variables

Use these variables in version-template to format the next version variables:

Use version-template for output that does not use Semantic Versioning.

version-template: 'ver $MAJOR'

semver.coerce('ver 1', true) // { version: '1.0.0' }

Version resolver

Any category with semver-increment contributes to $RESOLVED_VERSION. Use type: version-resolver categories when you want version resolution rules that do not also render a changelog section.

Before version resolution runs, any pre-include and pre-exclude categories filter the candidate pull requests. After that:

• type: changelog categories contribute only for pull requests assigned to that changelog category.
• type: version-resolver categories contribute from their own matches without rendering a changelog section.
• The highest matching increment wins across both category types.

Category order matters when exclusive is true. Release Drafter evaluates exclusivity independently for changelog and version resolver categories.

categories:
  - type: 'version-resolver'
    semver-increment: 'major'
    when:
      label: 'major'
  - type: 'version-resolver'
    semver-increment: 'minor'
    when:
      label: 'minor'
  - type: 'version-resolver'
    semver-increment: 'patch'
    when:
      label: 'patch'
  - type: 'version-resolver'
    semver-increment: 'patch'

This example:

• Uses matching categories to resolve major, minor, or patch.
• Uses the category with no when as the fallback when nothing else matches.
• Selects the highest Semantic Versioning increment across matching categories.

New contributor template variables

Use these variables in new-contributor-template:

Change template variables

Use these variables in change-template:

For a multiline author list, render each author with $AUTHOR and join them with a newline:

categories:
  - title: bug
    when:
      label: bug
  - title: todo
category-template: ''
change-template: |-
  - type: $CATEGORY
    message: |-
      $TITLE
    pull: $NUMBER
    authors:
      $AUTHORS
change-author-template: '- $AUTHOR'
change-authors-separator: "\n    "

Use $AUTHOR_MENTION instead of $AUTHOR in change-author-template to create GitHub mentions. Release Drafter renders GitHub App bots as linked mentions, for example [@dependabot[bot]](https://github.com/apps/dependabot). $CATEGORY preserves categories[].title; configure the title with the casing required by the output.

Categorize changes

The categories option defines the change classification sequence:

• type: changelog groups matching changes in the rendered release notes.
• type: pre-include keeps only matching changes for later processing.
• type: pre-exclude removes matching changes before changelog generation.
• type: version-resolver affects $RESOLVED_VERSION without rendering a changelog section.

pre-include always runs before pre-exclude, and both category types affect both changelog generation and version resolution.

Release Drafter evaluates categories in configuration order. By default, a pull request can match multiple categories of the same type. Setting exclusive: true on a changelog or version-resolver category stops later categories of that same type from also matching the same pull request.

Each category supports these keys:

Each category can define when in one of these forms:

• One condition object.
• An array of condition objects. A match against one object is sufficient.

Within one condition, conventional commit, label, and path predicates are combined with AND logic.

The condition keys are:

categories:
  - title: '🚀 Features'
    semver-increment: 'minor'
    when:
      - conventional:
          type: 'feat'
      - labels:
          - 'feature'
          - 'enhancement'
  - title: '🐛 Bug Fixes'
    when:
      - labels:
          - 'bug'
          - 'fix'
      - labels:
          - 'regression'
        paths:
          - 'src/**'
  - title: '⬆️ Dependencies'
    collapse-after: 0
    exclusive: true
    when:
      label: 'dependencies'
  - type: 'pre-exclude'
    when:
      label: 'skip-changelog'

The labels-mode and paths-mode options control the comparison of configured labels and path patterns. any is the default. Path matching uses the pull request's changed files.

The conventional option parses the pull request title as a conventional commit header. Set it to true to match any conventional title, or configure type/types, scope/scopes, and breaking:

categories:
  - title: 'Conventional Changes'
    when:
      conventional: true
  - title: '🚀 Features'
    semver-increment: 'minor'
    when:
      conventional:
        type: 'feat'
  - title: '💥 Breaking API Changes'
    semver-increment: 'major'
    when:
      conventional:
        type: 'feat'
        scope: 'api'
        breaking: true

Within a condition, label is shorthand for a single labels entry. If both label and labels are present, they are combined before labels-mode is applied. With the default labels-mode: any, labels: ["feature", "enhancement"] matches pull requests carrying either label.

Likewise, path is shorthand for a single paths entry. If both path and paths are present, they are combined before paths-mode is applied.

The matching modes are:

• any: at least one configured value matches
• all: every configured value matches
• only: every change value is included in the configured set
• exactly: the change values and configured values are the same set

If a condition does not configure any label/labels or path/paths, the corresponding *-mode setting has no effect.

An omitted or empty when matches all changes, but the meaning depends on the category type:

• At most one type: changelog category can omit when. It receives otherwise uncategorized changes.
• A type: version-resolver category with no when is the fallback when no other version resolver category matches.
• pre-include and pre-exclude categories with no when match every change.

Release Drafter groups changes that have matching labels or paths:

Use the Autolabeler action to add these labels.

Set collapse-after to collapse a category that has more than the specified number of pull requests. A value of 0 always collapses the category. A value of -1 disables collapsing.

categories:
  - title: '⬆️ Dependencies'
    collapse-after: 3
    when:
      label: 'dependencies'

Exclude changes

Use a type: pre-exclude category to exclude changes. For example, add this category to .github/release-drafter.yml:

categories:
  - type: 'pre-exclude'
    when:
      label: 'skip-changelog'

Release Drafter excludes changes with the skip-changelog label from the release draft.

Include changes

Use a type: pre-include category to include only a subset of changes. Release Drafter keeps changes that match at least one pre-include category. For example, add this category to .github/release-drafter.yml:

categories:
  - type: 'pre-include'
    when:
      labels:
        - 'app-foo'

Release Drafter includes only changes with the app-foo label in the release draft.

Exclude contributors

By default, $CONTRIBUTORS contains the names or usernames of all release contributors. Use exclude-contributors to remove specified usernames from the list.

exclude-contributors:
  - 'myusername'

Replacers

Use replacers to search and replace content in the generated changelog body. Release Drafter applies the regular expressions in configuration order.

replacers:
  - search: '/CVE-(\d{4})-(\d+)/g'
    replace: 'https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-\$1-\$2'
  - search: 'myname'
    replace: 'My Name'
  - search: '/- ([a-z])/g'
    replace: '- \u\$1' # Uppercase the first letter of each changelog entry

Release Drafter parses search as a regular expression. replace supports the Visual Studio Code replacement syntax.

Autolabeler

Use the Autolabeler action to add labels to pull requests.

name: Auto Label

on:
  pull_request:
    # Autolabeler handles these event types.
    types: [opened, reopened, synchronize]
  # Use pull_request_target to label pull requests from forks.
  # pull_request_target:
  #   types: [opened, reopened, synchronize]

permissions:
  contents: read

jobs:
  auto_label:
    permissions:
      pull-requests: write
    runs-on: ubuntu-slim
    steps:
      # Runs Autolabeler.
      - uses: release-drafter/release-drafter/autolabeler@v7

The available matchers are files for glob patterns and branch, title, and body for regular expressions. Autolabeler evaluates each matcher independently. It adds the label if at least one matcher succeeds.

# .github/release-drafter.yml
autolabeler:
  - label: 'chore'
    files:
      - '*.md'
    branch:
      - '/docs{0,1}\/.+/'
  - label: 'bug'
    branch:
      - '/fix\/.+/'
    title:
      - '/fix/i'
  - label: 'enhancement'
    branch:
      - '/feature\/.+/'
    body:
      - '/JIRA-[0-9]{1,4}/'

# Add the remaining Release Drafter configuration here.

Prerelease workflow

Release Drafter supports prerelease workflows. A typical sequence is:

• Publish a stable release, such as v3.5.0.
• Merge changes for the next release.
• Publish a prerelease, such as v3.5.0-rc.1.
• Merge more changes.
• Publish another prerelease, such as v3.5.0-rc.2.
• Publish the next stable release, such as v3.5.1.

Use the prerelease and prerelease-identifier action inputs or configuration keys to draft stable releases and prereleases.

jobs:
  update_full_release_draft:
    runs-on: ubuntu-slim
    steps:
      - uses: release-drafter/release-drafter@v7
        with:
          prerelease: false # the default
          # Add the remaining configuration here.
  update_prerelease_draft:
    runs-on: ubuntu-slim
    steps:
      - uses: release-drafter/release-drafter@v7
        with:
          prerelease: true
          # Use a Semantic Versioning identifier such as alpha, beta, or rc.
          prerelease-identifier: 'rc'

Both jobs run in parallel for changes to the configured branch.

• update_full_release_draft collects changes since v3.5.0 in a draft for v3.5.1, v3.6.0, or v4.0.0, according to the configuration.
• update_prerelease_draft collects changes since the last published prerelease. If no published prerelease exists, it collects changes since v3.5.0 in a draft for v3.5.0-rc.1. If v3.5.0-rc.1 exists, it collects changes since that release in a draft for v3.5.0-rc.2.

Set publish: true on update_prerelease_draft to publish each prerelease without manual approval. This setting removes the manual review of the prerelease contents.

Set include-pre-releases: true to include changes since the last prerelease instead of the last stable release. The stable release body then contains only changes after the last prerelease.

Projects that do not use Semantic Versioning

If your project does not follow Semantic Versioning, set version-template to define the $NEXT_{PATCH,MINOR,MAJOR}_VERSION values.

For example, set version-template to $MAJOR.$MINOR if the project does not use patch versions. If the current release is 1.0, $NEXT_MINOR_VERSION is 1.1.

Action inputs

The Release Drafter action accepts optional workflow inputs. Inputs override the corresponding values in release-drafter.yml.

Action outputs

The Release Drafter action sets outputs for later workflow steps.

GitHub Enterprise Server (GHES)

The GitHub Actions runtime creates the GitHub client through the GitHub adapter. It passes the action token and the runtime GITHUB_SERVER_URL, GITHUB_API_URL, and GITHUB_GRAPHQL_URL values to the GitHub adapter. If the GitHub Enterprise Server instance supports the required REST and GraphQL APIs, the same workflow can target it without github.com-specific configuration.

Contributing

See CONTRIBUTING.md for contribution instructions.

For help, open a GitHub issue.