Contents
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.
- [GitHub Actions] Check Pull request title
- [GitHub Actions] Automate Release notes
- [GitHub Actions] Check Pull request labels
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.
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 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.
Was my blog helpful? Please leave a comment at the bottom. it will be a great help to me!
App promotion
Deku.Deku created the applications with Flutter.If you have interested, please try to download them for free.
