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

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 to consider in the event; optional, defaults to all
    branches:
      - main
      - master

  # pull_request event is required only for autolabeler
  pull_request:
    # Only following types are handled by the action, but one can default to all as well
    types: [opened, reopened, synchronize]
  # pull_request_target event is required for autolabeler to support PRs from forks
  # pull_request_target:
  #   types: [opened, reopened, synchronize]

permissions:
  contents: read

jobs:
  update_release_draft:
    permissions:
      # write permission is required to create a github release
      contents: write
      # write permission is required for autolabeler
      # otherwise, read permission is required at least
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      # (Optional) GitHub Enterprise requires GHE_HOST variable set
      #- name: Set GHE_HOST
      #  run: |
      #    echo "GHE_HOST=${GITHUB_SERVER_URL##https:\/\/}" >> $GITHUB_ENV

      # Drafts your next Release notes as Pull Requests are merged into "master"
      - uses: release-drafter/release-drafter@v6
        # (Optional) specify config name to use, relative to .github/. Default: release-drafter.yml
        # with:
        #   config-name: my-config.yml
        #   disable-autolabeler: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

If you're unable to use GitHub Actions, you can use the Release Drafter GitHub App. Please refer to the Release Drafter GitHub App documentation for more information.

Once you’ve added Release Drafter to your repository, it must be enabled by adding a .github/release-drafter.yml configuration file to each repository. The configuration file must reside in your default branch, no other configurations will be accepted.

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'
    labels:
      - 'feature'
      - 'enhancement'
  - title: '🐛 Bug Fixes'
    labels:
      - 'fix'
      - 'bugfix'
      - 'bug'
  - title: '🧰 Maintenance'
    label: 'chore'
change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
version-resolver:
  major:
    labels:
      - 'major'
  minor:
    labels:
      - 'minor'
  patch:
    labels:
      - 'patch'
  default: patch
template: |
  ## Changes

  $CHANGES

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

Release Drafter also supports Probot Config, if you want to store your configuration files in a central repository. This allows you to share configurations between projects, and create a organization-wide configuration file by creating a repository named .github with the file .github/release-drafter.yml.

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

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

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

You can use any of the following variables in version-template to format the $NEXT_{PATCH,MINOR,MAJOR}_VERSION variables:

With the version-resolver option version number incrementing can be resolved automatically based on labels of individual pull requests. Append the following to your .github/release-drafter.yml file:

version-resolver:
  major:
    labels:
      - 'major'
  minor:
    labels:
      - 'minor'
  patch:
    labels:
      - 'patch'
  default: patch

The above config controls the output of the $RESOLVED_VERSION variable.

If a pull requests is found with the label major/minor/patch, the corresponding version key will be incremented from a semantic version. The maximum out of major, minor and patch found in any of the pull requests will be used to increment the version number. If no pull requests are found with the assigned labels, the default will be assigned.

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

Note: This is only relevant for GitHub app users as references is ignored when running as GitHub action due to GitHub workflows more powerful on conditions

References takes an list and accepts strings and regex. If none are specified, we default to the repository’s default branch usually master.

references:
  - master
  - v.+

Currently matching against any ref/heads/ and ref/tags/ references behind the scene

With the categories option you can categorize pull requests in release notes using labels. For example, append the following to your .github/release-drafter.yml file:

categories:
  - title: '🚀 Features'
    label: 'feature'
  - title: '🐛 Bug Fixes'
    labels:
      - 'fix'
      - 'bugfix'
      - 'bug'

Pull requests with the label "feature" or "fix" will now be grouped together:

Adding such labels to your PRs can be automated by using the embedded Autolabeler functionality (see below), PR Labeler or Probot Auto Labeler.

Optionally you can add a collapse-after entry to your category item, if the category has more than the defined collapse-after pull requests then it will show all pull requests collapsed for that category. Append the collapse-after integer to your category as following:

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

With the exclude-labels option you can exclude pull requests from the release notes using labels. For example, append the following to your .github/release-drafter.yml file:

exclude-labels:
  - 'skip-changelog'

Pull requests with the label "skip-changelog" will now be excluded from the release draft.

With the include-labels option you can specify pull requests from the release notes using labels. Only pull requests that have the configured labels will be included in the release draft. For example, append the following to your .github/release-drafter.yml file:

include-labels:
  - 'app-foo'

Pull requests with the label "app-foo" will be the only pull requests included in the release draft.

By default, the $CONTRIBUTORS variable will contain the names or usernames of all the contributors of a release. The exclude-contributors option allows you to remove certain usernames from that list. This can be useful if don't wish to include yourself, to better highlight only the third-party contributions.

exclude-contributors:
  - 'myusername'

You can search and replace content in the generated changelog body, using regular expressions, with the replacers option. Each replacer is applied in 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'

You can add automatically a label into a pull request, with the autolabeler option. Available matchers are files (glob), branch (regex), title (regex) and body (regex). Matchers are evaluated independently; the label will be set if at least one of the matchers meets the criteria.

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}/'

Release draft supports working with prereleases. It expects your workflow to be :

• A stable release is published, ex: v3.5.0
• You merge or add meaningful changes your users may want to see, but you are not quite ready for production
• You publish a prerelease, ex: v3.5.0-rc.1
• You merge more changes
• You publish another prerelease, ex: v3.5.0-rc.2
• You decide code is ready for production, you publish v3.5.1 (or another increment based on your changes)

With release-drafter, you can draft each of these releases and prereleases with the appropriate content using parameter 'prerelease' and 'prerelease-identifier' - available as either an input of from the config-file.

jobs:
  update_full_release_draft:
    runs-on: ubuntu-latest
    steps:
      - uses: release-drafter/release-drafter@v6
        with:
          prerelease: false # the default
          # ... rest of your config
  update_prerelease_draft:
    runs-on: ubuntu-latest
    steps:
      - uses: release-drafter/release-drafter@v6
        with:
          prerelease: true
          prerelease-identifier: 'rc' # Use semver identifiers : alpha, beta, rc, etc

Here, both jobs run in parallel every time you add changes to the configured branch.

• update_full_release_draft will pile-up changes since v3.5.0 inside a draft for v3.5.1 (or v3.6.0 or v4.0.0, depending on your config)
• update_prerelease_draft will pile-up changes since the last prerelease in a prerelease-draft. Changes are :
  • if no previous (published) prereleases are found - changes since v3.5.0 in a draft for v3.5.0-rc.1 (prerelease-draft)
  • or if v3.5.0-rc.1 exists (published) already - changes since v3.5.0-rc.1 in a draft for v3.5.0-rc.2 (prerelease-draft)

Some users like to run update_prerelease_draft with publish: true, such as prereleases are published immediately without the need for human intervention (or an external automation). Since prereleases are not meant to be stable in the first place, automation may be an acceptable risk for you too.

If your project doesn't follow Semantic Versioning you can still use Release Drafter, but you may want to set the version-template option to customize how the $NEXT_{PATCH,MINOR,MAJOR}_VERSION environment variables are generated.

For example, if your project doesn't use patch version numbers, you can set version-template to $MAJOR.$MINOR. If the current release is version 1.0, then $NEXT_MINOR_VERSION will be 1.1.

The Release Drafter GitHub Action accepts a number of optional inputs directly in your workflow configuration. These will typically override default behavior specified in your release-drafter.yml config.

The Release Drafter GitHub Action sets a couple of outputs which can be used as inputs to other Actions in the workflow (example).

If you have Node v10+ installed locally, you can run the tests, and a local app, using the following commands:

# Install dependencies
npm install

# Run the tests
npm run test

# Run the app locally
npm run test:watch

Once you've started the app, visit localhost:3000 and you'll get step-by-step instructions for installing it in your GitHub account so you can start pushing commits and testing it locally.

If you don’t have Node installed, you can use Docker Compose:

# Run the tests
docker compose run --rm app

Third-party contributions are welcome! 🙏🏼 See CONTRIBUTING.md for step-by-step instructions.

If you need help or have a question, let me know via a GitHub issue.

If you want to deploy your own copy of Release Drafter, follow the Probot Deployment Guide.

Run the following command:

git checkout master
git pull
npm version [major | minor | patch] -m "chore: release %s"

The command does the following:

• Run tests (preversion script)
• Bumps the version number in package.json and create corresponding tag
• Stage changes for git (version script)
• Commit and tag
• Push & push tag (postversion script)

After pushing, the release.yml workflow will trigger (on: push: tag), and :

• publish to npmjs
• publish the release draft
• update major tag (ex: pushing v6.2.1 bumps v6 to the same commit)