Skip to content
Drafts your next release notes as pull requests are merged into master.
Branch: master
Clone or download
Latest commit 1101a1d Mar 22, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update release-drafter.yml Jul 13, 2018
.vscode
design Add documentation Nov 10, 2018
lib
test
.dockerignore
.env.example
.gitignore
.prettierrc
.travis.yml
CODE_OF_CONDUCT.md
CONTRIBUTING.md
Dockerfile Update Node.js to v10.15.3 Mar 9, 2019
LICENSE
README.md
docker-compose.yml First commit Jun 28, 2018
index.js Replace deprecated editRelease with updateRelease Mar 18, 2019
package.json Pin dependency nock-knock to 2.0.0 Mar 21, 2019
renovate.json
yarn.lock Pin dependency nock-knock to 2.0.0 Mar 21, 2019

README.md

Release Drafter Logo

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


Install the GitHub App


NPM package

Usage

  1. Install the Release Drafter GitHub App, choosing the repositories you want releases automatically created.
  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
change-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:

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.

Template Variables

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.

Next Version Variables

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.

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.
$AUTHOR The 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

GitHub Installation Permissions

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.

Developing

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

Contributing

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.

Deployment

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

Releasing

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
You can’t perform that action at this time.