Release Drafter

Drafts your next release notes as pull requests are merged into master.
Screenshot of Release Drafter app

Repository

toolmantim/release-drafter

Authors

toolmantim

Updated

October 10, 2024

Used By

fossasia gorilla jenkinsci akka microsoft DevExpress beautify-web moovweb concourse theme-next

Usage

  1. Install the Release Drafter GitHub App into the repositories you wish to create releases in.
  2. Add a .github/release-drafter.yml configuration file to each repository.

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:

Screenshot of generated draft release

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

name-template: v$NEXT_PATCH_VERSION
tag-template: v$NEXT_PATCH_VERSION
categories:
  - title: 🚀 Features
    label: feature
  - title: 🐛 Bug Fixes
    label: fix
  - title: 🧰 Maintenance
    label: chore
tag-template: - $TITLE @$AUTHOR (#$NUMBER)
template: |
  ## Changes

  $CHANGES

Configuration Options

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

KeyRequiredDescription
templateRequiredThe template for the body of the draft release. Use template variables to insert values.
name-templateOptionalThe template for the name of the draft release. For example: "v$NEXT_PATCH_VERSION".
tag-templateOptionalThe template for the tag of the draft release. For example: "v$NEXT_PATCH_VERSION".
change-templateOptionalThe template to use for each merged pull request. Use change template variables to insert values. Default: "* $TITLE (#$NUMBER) @$AUTHOR".
no-changes-templateOptionalThe template to use for when there’s no changes. Default: "* No changes".
branchesOptionalThe branches to listen for configuration updates to .github/release-drafter.yml and for merge commits. Useful if you want to test the app on a pull request branch. Default is the repository’s default branch.
categoriesOptionalCategorize pull requests using labels. Refer to Categorize Pull Requests to learn more about this option.

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.

Template Variables

You can use any of the following variables in your template:

VariableDescription
$CHANGESThe markdown list of pull requests that have been merged.
$CONTRIBUTORSA comma separated list of contributors to this release (pull request authors, commit authors, and commit committers).
$PREVIOUS_TAGThe previous releases’s tag.

Next Version Variables

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

VariableDescription
$NEXT_PATCH_VERSIONThe 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_VERSIONThe 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_VERSIONThe next major version number. For example, if the last tag or release was v1.2.3, the value would be v2.0.0.

Change Template Variables

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

VariableDescription
$NUMBERThe number of the pull request, e.g. 42.
$TITLEThe title of the pull request, e.g. Add alien technology.
$AUTHORThe pull request author’s username, e.g. gracehopper.

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
    label: fix

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

Screenshot of generated draft release with categories

Get occasional updates on new apps & features.

Star

with by the Probot community

Code licensed ISC Docs licensed CC-BY-4.0