📝

GitHub Actions で簡単にバージョン番号付きリリースとリリースノートを作成する方法

2022/02/11に公開1件

GitHub

actions

releasenote

tech

対象読者判定フロー

以下の質問にはいかいいえで答えてください。

Q1: GitHub を使用していますか？

はいの方→次の質問に進んでください。
いいえの方→対象外です。すみません。

Q2: ソースコードなどの変更は全てプルリクエストで行って（＝master/main 直コミットはしていない（多少ならOK））いますか？

はいの方→次の質問に進んでください。
いいえの方→まずはプルリクエストベースの開発に切り替えてみてはいかがでしょう？　その後で続きを読んでください。

Q3: リリースノートをちゃんと書いていますか？

はいの方→基本的に対象外です。継続して書いていって下さい。楽をしたいと思ってる場合は続きを読んでください。
いいえの方→あなたは対象読者です！　この記事を読んで、お手軽自動生成でも良いのでリリースノートを作成しましょう！

はじめに

公開しているソフトウエアにバージョン番号を付けることは、利用者とのやり取りなど、様々な場面で重要になります。また、それぞれのバージョンで何が変更されたかを利用者が把握するためにも、リリースノートや ChangeLog は大事です。ですが、番号付けたりリリースノート書いたりするのってついつい面倒に思ってしまいますよね。

ここから先を読んでいる方は対象読者判定フローを通過した方なので、以下のような方のはずです。

GitHub を使っている
プルリクエストベースの開発をしている
だけど、リリースノートが書けていない
Releases や tag でバージョンを管理出来ている人もいれば、出来ていない人もいる

そんな方でも簡単にバージョンを管理してリリースノートを書けるよう、この記事では release-drafter という GitHub Action を使って、プルリクエストのタイトルなどから半自動的にリリースノートを作成する方法を説明します。同時に、このフローを回すことで、ちゃんとバージョン番号の付いたタグを付け、GitHub Releases にリリースを作成出来るようになります。また、プラスアルファとして追加で使うと便利なアクションも紹介します。

こんなツイートもあります。リリースノートをしっかり（楽して）書いて評価アップを目指しましょう！

利用例

まずは実際に使っているところをお見せしましょう。実際に利用しているリポジトリでリリースされたものです。私しか開発者はいないですが、私はこのリリースノートでは「mirakcに対応🙌」という内容を書き足しただけで、他は全部自動で作成されたものです。

以下の画面は、実際に利用しているリポジトリで、v0.2.21 として #99 までリリース出来ていて、#100、#101、#102 がマージしたものの未リリースの状態で Releases を見た画面です。v0.2.22 のリリースのドラフトが作成されている状態になっています。リリースノートとして、各プルリクエストのタイトルと、コントリビュータ（この例だと私と dependabot だけですが）が列挙されます。

Edit ボタンを押すと、このドラフトが編集出来ます。こんな画面になります。

必要に応じて記載内容を編集して、Publish release のボタンを押すと v0.2.22 のタグが打たれ、そのバージョンの Releases が自動的に生成されます。そして、この後別のプルリクエストをマージすると、今度は v0.2.23 のリリースのドラフトが自動的に生成されます。バージョン番号は自動的にインクリメントされるのです。

release-drafter のインストール

release-drafter のインストール（って言うのかな？）は簡単で、ドキュメントの Usage にあるワークフロー設定の YAML ファイルをリポジトリの .github/workflows ディレクトリに置き、設定ファイルをドキュメントの Example からコピーしてきます。先の例のリポジトリからコピーしても構いません。

機能の説明

release-drafter はいくつかの機能があるので、セクションを分けて解説します。

バージョンの採番

次に説明するドラフトリリースやタグのために、バージョン番号が必要になりますが、バージョン番号は自動で採番されます。採番されるバージョン番号は major.minor.patch という構成になっているのですが、リリースに含まれるプルリクエストの中に major や minor というラベルがついたプルリクエストがあると、バージョン番号の対応したパートがインクリメントされます。例えば、今が v1.2.3 までリリースされているとして、major が含まれていれば v2.0.0 に、minor だけなら v1.3.0 に、どちらも含まれていなければ v1.2.4 になります。

ドラフトリリース / タグの作成

先の利用例で見たように Releases に自動的に決定されたバージョン番号でドラフトリリースを自動で作成してくれます。このドラフトリリースを Publish することで、タグも自動的に打たれます。

このラベルとバージョン番号の対応は設定ファイルで書き換えることが出来ます。ドキュメントの Version Resolverにあります。

リリースノートの作成

作成されたドラフトリリースにはリリースノートの雛型が入っています。全体のテンプレートが気に入らない場合は template や header / footer で書き換えられます。それらの中ではドキュメントの Template Variables にある変数が使えます。

リリースに含まれるプルリクエストの列挙

ドラフトリリースのリリースノートには前回のリリースからその時点までにデフォルトブランチにマージされたプルリクエストが列挙されます。その際に、プルリクエストに付いているラベルに応じて分類してくれます。

分類の仕方と見せ方はドキュメントの Categorize Pull Requests に書いてあります。まあ、分類タイトルとラベルの組み合わせを列挙していくだけですね。サンプルでは絵文字も使って分かりやすいようにしています。

プルリクエストそれぞれの見せ方はデフォルトでも分かりやすいですが、何か変更したい場合はドキュメントの Change Template Variables の変数を使って change-template で設定することが出来ます。

また、それぞれのテンプレートで置き換えた後、最後に replacers を使って置換をすることが出来ます。自分は使ったことがないのですが、プライベートリポジトリで、JIRA などの外部の issue/チケット管理などを使っている場合には便利なのではないでしょうか。

autolabeler

プルリクエストの分類にはラベルが使われます。ですが、ラベルをつけ忘れてしまうこともありますよね。autolabeler はそのための機能です。プルリクエストのタイトル、本文、ブランチ名、変更されたファイルのパスによって自動的にプルリクエストにラベルを付けてくれます。

例えばこんな設定が .github/release-drafter.yml に書いてあったとします。

autolabeler:
  - label: feature
    branch:
      - '/^feat(ure)?[/-].+/'
  - label: bug
    branch:
      - '/^fix[/-].+/'
  - label: chore
    branch:
      - '/^chore[/-].+/'
  - label: refactor
    branch:
      - '/(refactor|refactoring)[/-].+/'
  - label: documentation
    branch:
      - '/doc(umentation)[/-].+/'
    files:
      - '*.md'
  - label: enhancement
    branch:
      - '/(enhancement|improve)[/-].+/'

このとき、feature/add-cool-feature というブランチからプルリクエストを作成すると、自動的に feature のラベルが付きます。ブランチ名に doc / documentation を付けるの忘れても、編集したファイルが *.md にマッチすれば、documentation のラベルが付きます。

開発者は何に気を付ければ良いか

上記の機能によって、autolabeler がプルリクエストに自動的にラベルを付け、そのラベルに従ってリリースノートの変更内容の分類が行われるわけです。
つまり、（基本的に）ブランチ名とプルリクエストのタイトルはちょっと考えて付けた方が良いということになります。ですが、逆に言えばそれだけ気を付ければ自動的にリリースノートが付きます。新しいバージョンをリリースするのも、ドラフトリリースの編集からぽちっとボタン 1 個押すだけです。どうです、簡単でしょう？

一緒に使うと便利なもの

actions/labeler

autolabeler の files だけバージョンみたいな感じです。all 条件が autolabeler には無いかな・・・

TimonVS/pr-labeler-action

これも autolabeler の branch だけバージョンみたいなもの。autolabeler で良い気がします。

micnncim/action-label-syncer

これはオススメ。GitHub の画面でポチポチと新しいラベルを作ったり、複数リポジトリで色を揃えたりする代わりに設定ファイルとワークフローアクションで完結させられます。導入・設定方法はドキュメントを読んでください。

dependabot

アクションではないですが、npmなどの依存関係を更新するプルリクエストを自動で作ってくれるボットです。ポイントは自動的に dependencies というラベルを付けてくれるので、release-drafter で分類がしやすいということです。

リリースビルド

バージョンを付けて Releases を作成したら、Windows アプリならビルドしてインストーラを添付したり、Docker コンテナやnpm パッケージならレジストリに push したりしたいですよね。それらの作業もワークフローで自動化しておくと良いです。

ただ、release-drafter を使う際は注意すべきことがあります。release-drafter のタグは GitHub の内部で作成されるため、push されるものではないということです。つまり、ワークフローのトリガー条件の on.push.tags に引っかからないのです。ではどうすれば良いかというと、実際に使っている例のように on.release の types: [published] を使えばOKです。これだけ気を付けてください。

おわりに

いかがでしたでしょうか。この記事で説明した release-drafter さえ設定してしまえば、以下の 3 つに気を付けるだけで、簡単に、見栄えの良いリリースノートが自動で作成されます！

プルリクエストベースで開発する（デフォルトブランチに直プッシュしない）
プルリクエストのタイトルに気を付ける
プルリクエストのブランチ名に気を付ける

たったこれだけです。簡単でしょう？　あなたも早速自分の（あるいは会社の）リポジトリに導入してみませんか？

Discussion

Kengo TODA 2022/02/12

release-drafterは最近Maven開発コミュニティでも、導入のためのPoCが作られていました。

また、GitHub Learning Labにrelease-drafterを実際に使ってみるコースがあるので、試してみたい方にはおすすめです :)