[GitHub Actions] Automate Release notes

Contents
Outline
Blog series
What is Release notes
Release Drafter
Release Drafter settings
Write Release notes Draft
Publish Release notes
Completed

Outline

When managing a project on GitHub, you can use the Release notes of GitHub to record the features added, bugs fixed, improvements, and deleted features in that version.

In this blog post, I will introduce how to automate the Release notes of GitHub using Release Drafter that is one of GitHub Actions.

Blog series

This blog post is part of a series. Please check out the other blog posts through the following link.

What is Release notes

Release notes is a document provided to users or developers when a new version or update is released in software development. This document contains information such as new features, fixed bugs, improvements, and deleted features in that version. Release notes helps users or other developers easily identify changes in a new version.

If you are using GitHub, you can check the Release notes in the Releases section of the repository.

GitHub Actions - Release Drafter, GitHub Releases

When you click the link of the Release notes, you can see the details of the Release notes as follows.

Release Drafter

Release Drafter is one of GitHub Actions that provides a feature to write Release notes using the title of Pull request.

Release Drafter

Release Drafter settings

To use Release Drafter, you need to add the Release Drafter settings file to the main branch.

In order to add it, create a .github/release-drafter.yml file and modify it as follows.

name-template: 'v$RESOLVED_VERSION'
tag-template: 'v$RESOLVED_VERSION'
version-resolver:
  major:
    labels:
      - 'major'
  minor:
    labels:
      - 'minor'
  patch:
    labels:
      - 'patch'
  default: patch
categories:
  - title: '⚠️ Breaking changes'
    labels:
      - 'breaking change'
  - title: '🚀 Features'
    labels:
      - 'feature'
  - title: '🐛 Bug Fixes'
    labels:
      - 'bug'
  - title: '📃 Documents'
    labels:
      - 'docs'
  - title: '🧩 Dependency Updates'
    labels:
      - 'deps'
      - 'dependencies'
      - 'bump'
      - 'chore'
    collapse-after: 5
  - title: '🔬 Others'
    labels:
      - 'style'
      - 'refactor'
      - 'test'
      - 'ci'
    collapse-after: 5
autolabeler:
  - label: 'breaking change'
    title:
      - '/!:/i'
  - label: 'feature'
    title:
      - '/feat:/i'
  - label: 'bug'
    title:
      - '/fix:/i'
  - label: 'style'
    title:
      - '/style:/i'
  - label: 'refactor'
    title:
      - '/refactor:/i'
  - label: 'test'
    title:
      - '/test:/i'
  - label: 'chore'
    title:
      - '/chore:/i'
  - label: 'docs'
    title:
      - '/docs:/i'
  - label: 'ci'
    title:
      - '/ci:/i'
  - label: 'dependencies'
    title:
      - '/deps:/i'
      - '/dependencies:/i'
      - '/bump:/i'
commitish: main
change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
change-title-escapes: '\<*_&'
template: |
  $CHANGES

Let’s take a closer look at the Release Drafter settings file.

name-template: 'v$RESOLVED_VERSION'
tag-template: 'v$RESOLVED_VERSION'
version-resolver:
  major:
    labels:
      - 'major'
  minor:
    labels:
      - 'minor'
  patch:
    labels:
      - 'patch'
  default: patch

This part is to specify the title of the Release notes of GitHub. $RESOLVED_VERSION is used to determine the version based on the labels of GitHub.

version-resolver is the part that specifies the labels used to raise the version by Pull request. If no label is specified, the patch version will be raised.

categories:
  - title: '⚠️ Breaking changes'
    labels:
      - 'breaking change'
  - title: '🚀 Features'
    labels:
      - 'feature'
  - title: '🐛 Bug Fixes'
    labels:
      - 'bug'
  - title: '📃 Documents'
    labels:
      - 'docs'
  - title: '🧩 Dependency Updates'
    labels:
      - 'deps'
      - 'dependencies'
      - 'bump'
      - 'chore'
    collapse-after: 5
  - title: '🔬 Others'
    labels:
      - 'style'
      - 'refactor'
      - 'test'
      - 'ci'
    collapse-after: 5

categories is the part that specifies the category of the Release notes based on the label of the Pull request. If there is a label specified in labels, the contents of the Release notes will be recorded in the category specified by the label.

collapse-after is an option that folds and shows the contents of the category if there are more than the specified number of Pull request.

autolabeler:
  - label: 'breaking change'
    title:
      - '/!:/i'
  - label: 'feature'
    title:
      - '/feat:/i'
  - label: 'bug'
    title:
      - '/fix:/i'
  - label: 'style'
    title:
      - '/style:/i'
  - label: 'refactor'
    title:
      - '/refactor:/i'
  - label: 'test'
    title:
      - '/test:/i'
  - label: 'chore'
    title:
      - '/chore:/i'
  - label: 'docs'
    title:
      - '/docs:/i'
  - label: 'ci'
    title:
      - '/ci:/i'
  - label: 'dependencies'
    title:
      - '/deps:/i'
      - '/dependencies:/i'
      - '/bump:/i'

Release Drafter provides a feature that automatically assigns label to GitHub based on the title of Pull request. autolabeler is the part that assigns label to Pull request based on the title of Pull request.

commitish: main

commitish is the part that specifies the branch to check the title of Pull request.

change-template: '- $TITLE @$AUTHOR (#$NUMBER)'

change-template is the part that specifies the contents of the Release notes. $TITLE is the title of Pull request, $AUTHOR is the user who created the Pull request, and $NUMBER is the number of Pull request.

change-title-escapes: '\<*_&'

change-title-escapes is the part that specifies the characters to escape from the title of Pull request.

template: |
  $CHANGES

template is the part that specifies the entire template of Release notes. $CHANGES represents the contents specified in change-template.

The Release Drafter settings file written like this is used when the Release Drafter action is executed, so it must be added to the main branch before writing and executing the Release Drafter action.

Write Release notes Draft

Next, let’s write the GitHub Actions that uses Release Drafter. Create a .github/workflows/release-drafter.yml file and modify it as follows.

name: Release Drafter

on:
  push:
    branches:
      - main
  pull_request:
    types:
      - opened
      - reopened
      - synchronize

permissions:
  contents: read

jobs:
  update_release_draft:
    permissions:
      contents: write
      pull-requests: write
      checks: write
    runs-on: ubuntu-latest
    steps:
      - uses: release-drafter/release-drafter@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

When the Pull request is created, this GitHub Actions uses autolabeler to automatically assign the appropriate label to the title of the Pull request.

And then, when the Pull request is merge to the main branch, the Release Drafter action is executed to write the Draft of the Release notes.

Publish Release notes

So far, we have looked at how to write the Draft of the Release notes using Release Drafter. Now let’s look at how to Publish the Draft of the Release notes.

To publish the Draft of the Release notes, create the .github/workflows/release.yml file and modify it as follows.

name: Release

on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'

jobs:
  release:
    permissions:
      contents: write
      pull-requests: write
      id-token: write
    runs-on: ubuntu-latest
    steps:
      - name: Get variables
        id: version
        run: echo "::set-output name=version::${GITHUB_REF#refs/tags/v}"

      - uses: actions/checkout@v4
        with:
          ref: v${{ steps.version.outputs.version }}

      - uses: release-drafter/release-drafter@v5
        with:
          tag: v${{ steps.version.outputs.version }}
          name: v${{ steps.version.outputs.version }}
          version: v${{ steps.version.outputs.version }}
          publish: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

These GitHub Actions operate on the Semantic Version of Git tag and distribute Release notes written in Draft using the publsih option of Release Drafter.

Completed

Done! We’ve seen how to automate Release notes using Release Drafter of GitHub Actions.

Release Drafter operates based on the label of Pull request. Therefore, it is important to check whether the appropriate label is set in Pull request.

On the next blog post, we will see how to check the label of Pull request using the PR Labels Checker action.