[GitHub Actions] Release notesの自動化

概要

GitHubでプロジェクトを管理する時、GitHubのRelease notesを使ってそのバージョンで追加された機能、修正されたバグ、改善された事項、削除された機能などを記録することができます。

今回のブログポストでは、GitHub Actionsの中で一つであるRelease Drafterを使ってGitHubのRelease notesの作成を自動化する方法について説明します。 이번 블로그 포스트에서는 GitHub Actions중 하나인 Release Drafter를 사용하여 GitHub의 Release notes 작성을 자동화하는 방법에 대해서 알아보겠습니다.

ブログシリーズ

このブログはシリーズで制作されました。次のリンクを通じて他のブログポストも確認してください。

Release notes とは

Release notesはソフト開発で新しいバージョンやアップデートがリリースされる時、ユーザーまたは開発者に提供される文書です。この文書にはそのバージョンで追加された機能、修正されたバグ、改善された事項、削除された機能などが記録されます。Release notes はユーザーまたは他の開発者が新しいバージョンに対する変更点を簡単に把握できるようにする役割を果たします。

GitHubを使っている場合、リポジトリ(Repository)に次のようにReleases項目を確認することができます。

GitHub Actions - Release Drafter, GitHub Releases

そのリンクをクリックすると次のようにRelease notesの詳細画面を確認することができます。

Release Drafter

Release DrafterはGitHub Actionsの中で一つであり、Pull requestのタイトルを使ってRelease notesを作成する機能を提供します。

Release Drafter

Release Drafter の設定

GitHub ActionsであるRelease Drafterを使うためにはmainブランチにRelease Drafterの設定ファイルを追加する必要があります。

これのため.github/release-drafter.ymlファイルを作って次のように修正します。

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

もっと詳しく見てみましょう。

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

GitHubのRelease notesのタイトルを指定する部分です。$RESOLVED_VERSIONはGitHubのlabelsを基にバージョンを決定する時に使われます。

version-resolverはPull requestでバージョンを上げるために使われるlabelsを指定する部分です。もし、どのlabelも指定されない場合、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

categoriesはPull requestのlabelを基にRelease notesの内容のカテゴリを指定する部分です。labelsに指定されたlabelがあれば、そのlabelに指定されたカテゴリにRelease notesに記録されます。

collapse-afterオプションは指定された個数以上の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はPull requestのタイトルを基にGitHubのlabelを自動で指定する機能を提供します。autolabelerはPull requestのタイトルを正規表現でチェックしてlabelを指定する部分です。

commitish: main

commitishはRelease DrafterがPull requestのタイトルをチェックするブランチを指定する部分です。

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

change-templateはRelease notesの内容を指定する部分です。$TITLEはPull requestのタイトル、$AUTHORはPull requestを作成したユーザー、$NUMBERはPull requestの番号を表します。

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

change-title-escapesはPull requestのタイトルから除外する文字を指定する部分です。.

template: |
  $CHANGES

templateはRelease notesの全体のテンプレートを指定する部分です。$CHANGESはchange-templateで指定した内容を表します。

このように作成したRelease Drafterの設定ファイルはRelease Drafterアクションが実行される時に使われるので、Release Drafterアクションを作成して実行する前にmainブランチに追加される必要があります。

Release notes の Draft 作成

次はRelease Drafterを使うGitHub Actionsを作成してみましょう。Release Drafterアクションを作成するため.github/workflows/release-drafter.ymlファイルを作って次のように修正します。

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 }}

このGitHub ActionsはPull requestが生成されたら、autolabelerを使ってPull requestのタイトルに合うlabelを自動で指定します。

そしてPull requestがmainブランチにmergeされたらRelease Drafterアクションが実行されてRelease notesのDraftを作成することになります。

Release notes 公開

今まではRelease Drafterを使ってRelease notesのDraftを作成する方法について説明しました。次はRelease notesのDraftを公開(Publish)する方法について説明します。

Release notesのDraftを公開するため.github/workflows/release.ymlファイルを作って次のように修正します。

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 }}