GitHub - release-drafter/release-drafter: Drafts your next release notes as pull requests are merged into master.

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:
  contents: write # allow GITHUB_TOKEN to update releases

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

Configuration Options

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

Key	Required	Description
`template`	Required	The template for the body of the draft release. Use template variables to insert values.
`header`	Optional	Will be prepended to `template`. Use template variables to insert values.
`footer`	Optional	Will be appended to `template`. Use template variables to insert values.
`category-template`	Optional	The template to use for each category. Use category template variables to insert values. Default: `"## $TITLE"`.
`name-template`	Optional	The template for the name of the draft release. For example: `"v$NEXT_PATCH_VERSION"`.
`tag-template`	Optional	The template for the tag of the draft release. For example: `"v$NEXT_PATCH_VERSION"`.
`tag-prefix`	Optional	A known prefix used to filter release tags. For matching tags, this prefix is stripped before attempting to parse the version. Default: `""`
`version-template`	Optional	The template to use when calculating the next version number for the release. Useful for projects that don't use semantic versioning. Default: `"$MAJOR.$MINOR.$PATCH$PRERELEASE"`
`change-template`	Optional	The template to use for each merged pull request. Use change template variables to insert values. Default: `"* $TITLE (#$NUMBER) @$AUTHOR"`.
`change-title-escapes`	Optional	Characters to escape in `$TITLE` when inserting into `change-template` so that they are not interpreted as Markdown format characters. Default: `""`
`no-changes-template`	Optional	The template to use for when there’s no changes. Default: `"* No changes"`.
`references`	Optional	The references to listen for configuration updates to `.github/release-drafter.yml`. Refer to References to learn more about this
`categories`	Optional	Categorize pull requests using labels. Refer to Categorize Pull Requests to learn more about this option.
`exclude-labels`	Optional	Exclude pull requests using labels. Refer to Exclude Pull Requests to learn more about this option.
`include-labels`	Optional	Include only the specified pull requests using labels. Refer to Include Pull Requests to learn more about this option.
`exclude-contributors`	Optional	Exclude specific usernames from the generated `$CONTRIBUTORS` variable. Refer to Exclude Contributors to learn more about this option.
`no-contributors-template`	Optional	The template to use for `$CONTRIBUTORS` when there's no contributors to list. Default: `"No contributors"`.
`replacers`	Optional	Search and replace content in the generated changelog body. Refer to Replacers to learn more about this option.
`sort-by`	Optional	Sort changelog by merged_at or title. Can be one of: `merged_at`, `title`. Default: `merged_at`.
`sort-direction`	Optional	Sort changelog in ascending or descending order. Can be one of: `ascending`, `descending`. Default: `descending`.
`prerelease`	Optional	Whether to draft a prerelease, with changes since another prerelease (if applicable). Default `false`.
`prerelease-identifier`	Optional	A string indicating an identifier (alpha, beta, rc, etc), to increment the prerelease version. This automatically enables `prerelease` if not already set to `true`. Default `''`.
`include-pre-releases`	Optional	When looking for the last published release to scan changes up-to, include pre-releases. Has no effect if using `prerelease: true` (already enabled). Default `false`.
`latest`	Optional	Mark the release as latest. Only works for published releases. Can be one of: `true`, `false`, `legacy`. Default `true`.
`version-resolver`	Optional	Adjust the `$RESOLVED_VERSION` variable using labels. Refer to Version Resolver to learn more about this
`commitish`	Optional	The release target, i.e. branch or commit it should point to. Default: the ref that release-drafter runs for, e.g. `refs/heads/master` if configured to run on pushes to `master`.
`filter-by-range`	Optional	Filter releases that satisfies a semver range. Evaluates the tag name againts node's `semver.satisfies()`. Default : `"*"`.
`filter-by-commitish`	Optional	Filter previous releases to consider only those with the target matching `commitish`. Default: `false`.
`include-paths`	Optional	Restrict pull requests included in the release notes to only the pull requests that modified any of the paths in this array. Supports files and directories. Default: `[]`
`exclude-paths`	Optional	Exclude pull requests from the release notes if they modified any of the paths in this array. Supports files and directories. If used with `include-paths`, exclusion takes precedence. Default: `[]`
`pull-request-limit`	Optional	Limit for associatedPullRequests API call. Use this when working with long-lived non-default branches. See #1354. Default: `5`
`history-limit`	Optional	Size of the pagination window when walking the repo. Can avoid erratic 502s from Github. Default: `15`
`initial-commits-since`	Optional	When drafting your first release, limit the amount of scanned commits. Expects an ISO 8601 date, ex: `"2025-06-18T10:29:51Z"`. Default: `""` (unlimited)

Template Variables

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

Variable	Description
`$CHANGES`	The markdown list of pull requests that have been merged.
`$CONTRIBUTORS`	A comma separated list of contributors to this release (pull request authors, commit authors, and commit committers).
`$PREVIOUS_TAG`	The previous releases’s tag.
`$REPOSITORY`	Current Repository
`$OWNER`	Current Repository Owner

Category Template Variables

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

Variable	Description
`$TITLE`	The category title, e.g. `Features`.

Next Version Variables

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

Variable	Description
`$NEXT_PATCH_VERSION`	The next patch version number. For example, if the last tag or release was `v1.2.3`, the value would be `v1.2.4`. This is the most commonly used value.
`$NEXT_MINOR_VERSION`	The next minor version number. For example, if the last tag or release was `v1.2.3`, the value would be `v1.3.0`.
`$NEXT_MAJOR_VERSION`	The next major version number. For example, if the last tag or release was `v1.2.3`, the value would be `v2.0.0`.
`$NEXT_PRERELEASE_VERSION`	The next prerelease suffix. Depends on `prerelease-identifier`. Ex: `v1.2.3-beta.3`. Default : `''`
`$RESOLVED_VERSION`	The next resolved version number, based on GitHub labels. Refer to Version Resolver to learn more about this.

Next Version Component Helpers

For each of the $NEXT_{MAJOR,MINOR,PATCH}_VERSION variables, additional component helper variables are available that extract individual version components:

Variable	Description
`$NEXT_MAJOR_VERSION_MAJOR`	Major component of `$NEXT_MAJOR_VERSION`.
`$NEXT_MAJOR_VERSION_MINOR`	Minor component of `$NEXT_MAJOR_VERSION`.
`$NEXT_MAJOR_VERSION_PATCH`	Patch component of `$NEXT_MAJOR_VERSION`.
`$NEXT_MINOR_VERSION_MAJOR`	Major component of `$NEXT_MINOR_VERSION`.
`$NEXT_MINOR_VERSION_MINOR`	Minor component of `$NEXT_MINOR_VERSION`.
`$NEXT_MINOR_VERSION_PATCH`	Patch component of `$NEXT_MINOR_VERSION`.
`$NEXT_PATCH_VERSION_MAJOR`	Major component of `$NEXT_PATCH_VERSION`.
`$NEXT_PATCH_VERSION_MINOR`	Minor component of `$NEXT_PATCH_VERSION`.
`$NEXT_PATCH_VERSION_PATCH`	Patch component of `$NEXT_PATCH_VERSION`.
`$NEXT_PRERELEASE_VERSION_PRERELEASE`	Prerelease segment of `$NEXT_PRERELEASE_VERSION`. Ex : `'-beta.3'`

Version Template Variables

You can use any of the following variables in version-template to format the Next Version Variables:

Variable	Description
`$PATCH`	The patch version number.
`$MINOR`	The minor version number.
`$MAJOR`	The major version number.
`$PRERELEASE`	The prerelease suffix (for example `-rc.0`) or an empty string.

You may want to use this when producing non semver output.

version-template: 'ver $MAJOR'

Important

If you want the next release-drafter run to parse your version, stick to versions parseable by semver.coerce() (we enbale loose mode)

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

If you simply want a verbose title for your releases, use the name-template config, and leave versions strictly semver-compliant.

Version Resolver

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.

Change Template Variables

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

Variable	Description
`$NUMBER`	The number of the pull request, e.g. `42`.
`$TITLE`	The title of the pull request, e.g. `Add alien technology`. Any characters excluding @ and # matching `change-title-escapes` will be prepended with a backslash so that they will appear verbatim instead of being interpreted as markdown format characters. @s and #s if present in `change-title-escapes` will be appended with an HTML comment so that they don't become mentions.
`$AUTHOR`	The pull request author’s username, e.g. `gracehopper`.
`$BODY`	The body of the pull request e.g. `Fixed spelling mistake`.
`$URL`	The URL of the pull request e.g. `https://github.com/octocat/repo/pull/42`.
`$BASE_REF_NAME`	The base name of of the base Ref associated with the pull request e.g. `master`.
`$HEAD_REF_NAME`	The head name of the head Ref associated with the pull request e.g. `my-bug-fix`.

References

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

Categorize Pull Requests

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 action.

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'

Exclude Pull Requests

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.

Include Pull Requests

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.

Exclude Contributors

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'

Replacers

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'
  - search: '/- ([a-z])/g'
    replace: '- \u$1' # Uppercase the first letter of each changelog entry

search will be parsed to a RegExp, and replace supports substitution in the same flavour VSCode does.

Autolabeler

You can add automatically a label into a pull request, with the autolabeler action.

steps:
  # runs autolabeler
  - uses: release-drafter/release-drafter/autolabeler@latest

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.

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

# ... rest of release-drafter config

Prerelease workflow

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.

Important

prerelease-identifier is not required when prerelease is enabled, but your prerelease may not be named after / be associated with a tag that is semver-compliant to an actual prerelease.
when specified, prerelease-identifier enables prerelease: true

If you want your stable releases to include changes since the last prerelease instead of the last stable release, use include-pre-releases: true. This can reduce the number of changes included in the stable release body, but diverges from the standard workflow depicted above.

Projects that don't use Semantic Versioning

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.

Action Inputs

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.

Input	Description
`config-name`	If your workflow requires multiple release-drafter configs it be helpful to override the config-name. The config should still be located inside `.github` as that's where we are looking for config files.
`token`	Access token used to make requests against the GitHub API. Defaults to `${{ github.token }}`
`dry-run`	When enabled, no write operations (creating/updating releases or adding labels) are performed. Instead, the action logs what it would have done. Default : `false`
`name`	The name that will be used in the GitHub release that's created or updated. This will override any `name-template` specified in your `release-drafter.yml` if defined.
`tag`	The tag name to be associated with the GitHub release that's created or updated. This will override any `tag-template` specified in your `release-drafter.yml` if defined.
`filter-by-range`	Filter releases that satisfies a semver range. Evaluates the tag name againts node's `semver.satisfies()`.
`version`	The version to be associated with the GitHub release that's created or updated. This will override any version calculated by the release-drafter.
`publish`	A boolean indicating whether the release being created or updated should be immediately published. This may be useful if the output of a previous workflow step determines that a new version of your project has been (or will be) released, as with `salsify/action-detect-and-tag-new-version`.
`prerelease`	Whether to draft a prerelease, with changes since another prerelease (if applicable). Default `false`.
`prerelease-identifier`	A string indicating an identifier (alpha, beta, rc, etc), to increment the prerelease version. This automatically enables `prerelease` if not already set to `true`. Default `''`.
`include-pre-releases`	When looking for the last published release to scan changes up-to, include pre-releases. Has no effect if using `prerelease: true` (already enabled). Default `false`.
`latest`	A string indicating whether the release being created or updated should be marked as latest.
`commitish`	A string specifying the target branch for the release being created.
`header`	A string that would be added before the template body.
`footer`	A string that would be added after the template body.
`initial-commits-since`	When drafting your first release, limit the amount of scanned commits. Expects an ISO 8601 date, ex: `"2025-06-18T10:29:51Z"`. Default: `""` (unlimited)

Action Outputs

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

Output	Description
`id`	The ID of the release that was created or updated.
`name`	The name of this release.
`tag_name`	The name of the tag associated with this release.
`body`	The body of the drafted release, useful if it needs to be included in files.
`html_url`	The URL users can navigate to in order to view the release. i.e. `https://github.com/octocat/Hello-World/releases/v1.0.0`.
`upload_url`	The URL for uploading assets to the release, which could be used by GitHub Actions for additional uses, for example the `@actions/upload-release-asset GitHub Action`.
`resolved_version`	Version resolved by Version Resolver. i.e. `6.3.1`
`major_version`	Major part of resolved version by Version Resolver. i.e. `6` for version `6.3.1`
`minor_version`	Minor part of resolved version by Version Resolver. i.e. `3` for version `6.3.1`
`patch_version`	Patch part of resolved version by Version Resolver. i.e. `1` for version `6.3.1`

Contributing

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

Important

Before pushing, run npm run all to format, lint, type-check, test, and regenerate all build artifacts. The CI pipeline enforces that no uncommitted changes remain after these steps.

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

Name		Name	Last commit message	Last commit date
Latest commit History 1,417 Commits
.devcontainer		.devcontainer
.github		.github
.licenses/npm		.licenses/npm
.vscode		.vscode
autolabeler		autolabeler
badges		badges
dist		dist
docs		docs
drafter		drafter
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.node-version		.node-version
.npmrc		.npmrc
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
biome.jsonc		biome.jsonc
mise.toml		mise.toml
package-lock.json		package-lock.json
package.json		package.json
schema.json		schema.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Usage

Configuration

Example

Configuration Options

Template Variables

Category Template Variables

Next Version Variables

Next Version Component Helpers

Version Template Variables

Version Resolver

Change Template Variables

References

Categorize Pull Requests

Exclude Pull Requests

Include Pull Requests

Exclude Contributors

Replacers

Autolabeler

Prerelease workflow

Projects that don't use Semantic Versioning

Action Inputs

Action Outputs

Contributing

About

Uh oh!

Releases 56

Packages

Uh oh!

Uh oh!

Contributors 91

Languages

Folders and files

Latest commit

History

Repository files navigation

Usage

Configuration

Example

Configuration Options

Template Variables

Category Template Variables

Next Version Variables

Next Version Component Helpers

Version Template Variables

Version Resolver

Change Template Variables

References

Categorize Pull Requests

Exclude Pull Requests

Include Pull Requests

Exclude Contributors

Replacers

Autolabeler

Prerelease workflow

Projects that don't use Semantic Versioning

Action Inputs

Action Outputs

Contributing

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 56

Packages 0

Uh oh!

Uh oh!

Contributors 91

Languages

Packages