Drafts your next release notes as pull requests are merged into master. Built with Probot.
- Install the Release Drafter GitHub App, choosing the repositories you want releases automatically created.
- Add a
.github/release-drafter.yml
configuration file to each repository.
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$NEXT_PATCH_VERSION 🌈
tag-template: v$NEXT_PATCH_VERSION
categories:
- title: 🚀 Features
label: feature
- title: 🐛 Bug Fixes
label: fix
- title: 🧰 Maintenance
label: chore
change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
template: |
## Changes
$CHANGES
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. |
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" . |
change-template |
Optional | The template to use for each merged pull request. Use change template variables to insert values. Default: "* $TITLE (#$NUMBER) @$AUTHOR" . |
no-changes-template |
Optional | The template to use for when there’s no changes. Default: "* No changes" . |
branches |
Optional | The 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. |
categories |
Optional | Categorize 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
.
You can use any of the following variables in your template
:
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. |
You can use any of the following variables in your template
, 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 . |
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 . |
$AUTHOR |
The pull request author’s username, e.g. gracehopper . |
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:
Release Drafter requires full write, because GitHub does not offer a limited scope for only writing releases. Don't install Release Drafter to your entire GitHub account — only add the repositories you want to draft releases on.
If you have Node v10+ installed locally, you can run the tests, and a local app, using the following commands:
# Install dependencies
yarn
# Run the tests
npm test
# Run the app locally
npm run dev
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 npm test
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]
The command does the following:
- Ensures you’re on master and don’t have local, un-commited changes
- Bumps the version number in package.json based on major, minor or patch
- Runs the
postversion
npm script in package.json, which:- Pushes the tag to GitHub
- Publishes the npm release
- Deploys to Now
- Opens the GitHub releases page so you can publish the release notes