onenashev/jenkins-release-drafter repository overview

⁠

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

⁠Usage

⁠GitHub Actions

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-management.yml, with the following:

name: Release Management

on:
  push:
    # branches to consider in the event; optional, defaults to all
    branches:
      - master

jobs:
  update_draft_release:
    runs-on: ubuntu-latest
    steps:
      # Drafts your next Release notes as Pull Requests are merged into "master"
      - uses: toolmantim/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

⁠GitHub App

You can also install the Release Drafter GitHub App⁠, choosing the repositories for which you want releases automatically created.

⁠Configuration

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.

⁠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$NEXT_PATCH_VERSION 🌈'
tag-template: 'v$NEXT_PATCH_VERSION'
categories:
  - title: '🚀 Features'
    labels:
      - 'feature'
      - 'enhancement'
  - title: '🐛 Bug Fixes'
    labels:
      - 'fix'
      - 'bugfix'
      - 'bug'
  - 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:

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:

⁠Next Version Variables

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

⁠Version Template Variables

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

⁠Change Template Variables

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

⁠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 PR Labeler⁠ or Probot Auto Labeler⁠.

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

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

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

⁠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