GitHub Actions で Release notes の自動生成はもっと楽にできる
TL;DR
GitHub Actions から Release を自動生成するために GITHUB_TOKEN の権限でcontents: writeを付与する。
permissions:
contents: write
GitHub CLI と --generate-notes オプションを使って Release notes を自動生成する。
- name: Create Release
run: |
gh release create [tag] --generate-notes [attachment-file]
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
自動生成された Release notes のサンプル。
詳細
実際に自分が使っている GitHub Actions の設定を元に説明する。
この Actions は、v* というタグが push されたら、pnpm build でビルドして、その圧縮ファイルを添付して Release を作成する。
name: Build and Release on Tag
on:
push:
tags:
- 'v*'
permissions:
contents: write
jobs:
build_and_release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: pnpm/action-setup@v4
with:
version: 9
- run: pnpm install --frozen-lockfile
- run: pnpm build
- name: Archive Production Build
run: |
tar -czf ${{github.ref_name}}.tar.gz ./dist
- name: Create Release
run: |
gh release create ${{github.ref_name}} --generate-notes ${{github.ref_name}}.tar.gz
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
GitHub の Release を作成する gh release create
GitHub の Release を作成するコマンド。
gh コマンドは GitHub Actions にデフォルトでインストールされているので、特になにかインストールすることなく使える。
API ドキュメントの方を見ると、"Contents" repository permissions (write) が必要と書いてある。ので、GitHub Actions の設定でも permissions: contents: write を付与している。
permissions:
contents: write
git のタグ名を取得する ${{github.ref_name}}
${{github.ref_name}} は、GitHub Actions で使える変数の一つで、この場合は git のタグ名を取得している。
この値はトリガーとなったイベントによって変わるので注意。
Release notes を自動生成する --generate-notes
--generate-notes オプションを使うことで、自動的に Release notes を生成してくれる。
--generate-notes
Automatically generate title and notes for the release
Use automatically generated release notes
$ gh release create v1.2.3 --generate-notes
https://cli.github.com/manual/gh_release_create
検討した他の方法
GitHub に tag を push した時に、自動で build したファイルを Release に添付して公開するような Actions を作りたかった。
実装方針は以下のことを考えていた。
- なるべく公式の Actions を使う
- 簡単に済むなら、外部 Actions を使わない
1. actions/create-release + actions/upload-release-asset
GitHub 公式の Actions である actions/create-release と actions/upload-release-asset を使う方法。
しかし、これらの Actions は Public archive になってしまったので、使えないことはないが使わない方が良いと思った。
Please note: This repository is currently unmaintained by a team of developers at GitHub. The repository is here and you can use it as an example, or in Actions. However please be aware that we are not going to be updating issues or pull requests on this repository.
2. softprops/action-gh-release を使う
actions/create-release から Maintained Actions として紹介されていて、もっともスター数が多かったもの。
以下のようにコードを書くと、Release を作成してくれる。
- name: Create Release
uses: softprops/action-gh-release@v1
with:
tag_name: ${{github.ref_name}}
name: Release ${{github.ref_name}}
generate_release_notes: true
files: ${{github.ref_name}}.tar.gz
これは使いやすくて良いのだが、今回のものは gh コマンドで簡単に済んでしまう内容だったので、外部 Actions への依存を減らすために使わないことにした。
3. REST API で頑張る
GitHub の REST API を使って Release を作成するための情報を一つ一つ取得していく方法。
この場合、以下の記事を参考にすると「前回のリリースのバージョンを取得」「前回リリースからの差分をもとに Release note を自動生成」「Release を作成」の 3 つのステップが最低でも必要になる。
この記事で紹介した gh コマンドを使う方法や softprops/action-gh-release を使う方法と比べると、かなり手間がかかるので使わないことにした。
Discussion