更新日：2025年6月5日
13分で読めます
チュートリアル：GitLabでリリース自動化とリリースノート自動生成
GitLabのChangelog APIを使用すると、リリースアーティファクト、リリースノートなどの変更をまとめた、包括的な変更履歴の生成を自動化できます。
2025年の更新情報 GitLab Changelog APIは進化を続けており、今回のブログでは取り上げていない優れた新機能も追加されています。たとえば、コミット履歴からテンプレート化された値を使ってカスタムの変更履歴を提供できるようになっています。詳しくは、変更履歴に関する公式ドキュメントをご覧ください。
ユーザーが頼りにしているソフトウェアを開発する際には、各リリースでの変更点を効果的に伝えることが不可欠です。新機能や変更点、削除された内容をきちんと伝えることで、ユーザーはソフトウェアを最大限に活用でき、アップグレード時の思わぬトラブルも回避できます。
これまで、リリースノートの作成や変更履歴の管理は手間のかかる作業でした。デベロッパーが外部ツールで変更を追跡したり、リリースマネージャーがマージ履歴を手作業で確認したりする必要があったためです。GitLabのChangelog APIを使うと、Gitリポジトリに記録された豊富な履歴情報を活用して、リリースノートの作成や変更履歴の管理を簡単に行うことができます。
このチュートリアルでは、GitLabを使ったリリースの自動化について詳しく説明します。リリースアーティファクトの生成、リリースノートの作成、そしてユーザーに関係する変更点をすべて網羅した包括的な変更履歴の生成方法について取り上げます。
GitLabにおけるリリース
まずは、GitLabでリリースがどのように機能しているのかを見ていきましょう。
GitLabにおけるリリースとは、Gitタグで識別される特定のコードバージョンのことを指します。このリリースには、前回のリリース以降に行われた変更内容（およびリリースノート）や、そのバージョンのコードからビルドされた関連アーティファクト（Dockerイメージ、インストールパッケージ、ドキュメントなど）が含まれます。
リリースは、GitLabのUIを使って作成・管理することもできますし、Release APIを呼び出すか、CIパイプラインの中に特別なreleaseジョブを定義することでも実現できます。このチュートリアルでは、CI/CDパイプライン内のreleaseジョブを使用します。これにより、テストやコードスキャンなどに使っている自動化プロセスを、リリースの実行にも拡張できるようになります。
リリースを自動化するために、まず確認しなければならないことがあります。「リリースノートや変更履歴を作成するための変更情報は、どこから取得するのか？」その答えは、Gitリポジトリです。コミットメッセージやマージコミットの履歴を通じて、豊富な開発履歴が得られます。この情報を活用して、リリースノートや変更履歴を自動生成できるか試してみましょう。
コミットトレーラーの導入
コミットトレーラーとは、Gitのコミットメッセージの末尾に追加する、構造化されたエントリーのことです。書き方はシンプルで、<HEADER>:<BODY>という形式のメッセージをコミットの最後に追加するだけです。これにより、gitのコマンドラインインターフェース（CLI）ツールがそれらを解析して、他のシステムで利用できるようになります。たとえば、すでに使ったことがあるかもしれませんが、git commit --sign-offでコミットに署名する機能もこの仕組みを使っています。これは、Signed-off-by: <あなたの名前>というトレーラーをコミットに追加することで実現されています。このトレーラーには、好きな構造化データを自由に追加できるので、変更履歴に役立つ情報を保存する場所として非常に便利です。
実際に、コミットにChangelog: <added/changed/removed>というトレーラーを使うと、GitLabのChangelog APIがそれを解析し、自動的に変更履歴を生成してくれます！
それでは、実際のコードベースに変更を加えてリリースを行い、リリースノートと変更履歴のエントリーを生成する手順を見ていきましょう。
サンプルプロジェクトについて
今回のブログでは、シンプルなPythonのWebアプリのリポジトリを使っています。仮に、このアプリケーションのバージョン1.0.0がちょうどリリースされたばかりで、これが現在のコードのバージョンだとしましょう。また、GitLab上で1.0.0のリリースも作成してありますが、これはまだ自動化されたリリースパイプラインを作っていないため、手動で作成しました。
変更の実施
現在は開発を急ピッチで進めている段階なので、今日はアプリケーションのバージョン2.0.0のリリース作業を進めていきます。2.0.0リリースでは、アプリに新機能の「チャットボット」を追加します。そして、量子ブロックチェーン機能は削除します。これは最初のベンチャーキャピタル向けに必要だっただけなので、もう不要です。さらに、2.0.0リリースに向けて、CI/CDパイプラインに自動リリースジョブも追加する予定です。
まずは不要な機能の削除から始めましょう。不要な部分を削除したマージリクエストを作成しました。ここで重要なのは、コミットメッセージにChangelog: removedトレーラーを含めることです。これを行う方法はいくつかあります。たとえば、最初からコミットに直接含めたり、インタラクティブリベースを使ってCLIで後から追加したりもできます。しかし、今回の状況では、一番簡単な方法は最後にGitLabのEdit commit messageボタンを使って、マージコミットにトレーラーを追加する方法だと思います。
この方法を使えば、マージコミットのタイトルをもっと簡潔なものに変更することもできます。ここでは、マージコミットのタイトルを'Remove Unused Features'に変更しました。これは変更履歴のエントリに表示されます。
次に、2.0.0リリース用の新機能を追加しましょう。ここでも、新機能を含む別のマージリクエストを開き、マージコミットを編集してChangelog: addedトレーラーを追加し、コミットのタイトルをより簡潔に編集するだけです。
これで、バージョン2.0.0をリリースする準備はほとんど整いました。ただし、今回は手動でリリースを作成したくありません。そのため、リリースの前に.gitlab-ci.ymlファイルにいくつかのジョブを追加し、コードに2.0.0のような新しいバージョンのタグを付けた際に、自動でリリース処理を行い、対応するリリースノートや変更履歴のエントリを生成するようにします。
**注：**変更履歴のトレーラーを強制したい場合は、Dangerのようなツールを使用して、マージリクエストの規則を自動的にチェックする方法を検討してください。
自動リリースパイプラインの構築
パイプラインを機能させるには、プロジェクトアクセストークンを作成し、GitLabのAPIを呼び出して変更履歴のエントリーを生成できるようにする必要があります。APIスコープを指定してプロジェクトアクセストークンを作成し、それをCI_API_TOKENという名前のCI/CD変数として保存します。この変数を参照して、APIの認証を行います。
次に、gitlab-ci.ymlファイルに以下の2つの新しいジョブを追加します。
prepare_job:
stage: prepare
image: alpine:latest
rules:
- if: '$CI_COMMIT_TAG =~ /^v?\d+\.\d+\.\d+$/'
script:
- apk add curl jq
- 'curl -H "PRIVATE-TOKEN: $CI_API_TOKEN" "$CI_API_V4_URL/projects/$CI_PROJECT_ID/repository/changelog?version=$CI_COMMIT_TAG" | jq -r .notes > release_notes.md'
artifacts:
paths:
- release_notes.md
release_job:
stage: release
image: registry.gitlab.com/gitlab-org/release-cli:latest
needs:
- job: prepare_job
artifacts: true
rules:
- if: '$CI_COMMIT_TAG =~ /^v?\d+\.\d+\.\d+$/'
script:
- echo "Creating release"
release:
name: 'Release $CI_COMMIT_TAG'
description: release_notes.md
tag_name: '$CI_COMMIT_TAG'
ref: '$CI_COMMIT_SHA'
assets:
links:
- name: 'Container Image $CI_COMMIT_TAG'
url: "https://$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA"
上記の設定では、prepare_jobがcurlとjqを使ってGitLabのChangelog APIエンドポイントを呼び出し、その結果をrelease_jobに渡して、リリースの作成を行います。詳しく見ていきましょう。
- まず、先ほど作成したプロジェクトアクセストークンを使ってGitLabのChangelog APIを呼び出し、リリースノートを生成します。そして、その出力をアーティファクトとして保存します。
- バージョンには
$CI_COMMIT_TAG変数を使用しています。この仕組みが機能するには、タグにセマンティックバージョニング（たとえば2.0.0のような形式）を使用する必要があります。そのため、リリースジョブには、セマンティックバージョンのタグが付いているかどうかを確認するrulesセクションを追加しています。- GitLabのChangelog APIを使うには、セマンティックバージョニングが必要です。この形式を用いて、現在のリリースとの比較対象となる最新リリースを特定します。
- GitLabが提供する公式の
release-cliイメージを使用しています。ジョブ内でreleaseキーワードを使うには、このrelease-cliが必要です。 releaseキーワードを使用して、GitLab上にリリースを作成します。これは、リリースの作成と必須フィールドの入力のために確保されている特別なジョブキーワードです。- リリースの
descriptionには、ファイルを引数として渡すことができます。今回の例では、prepare_jobで生成し、アーティファクトとしてこのジョブに渡されたファイルを使っています。 - さらに、パイプラインの早い段階でビルドされているコンテナイメージも、リリースアセットとして追加しています。ビルドプロセスの中で作成したバイナリやドキュメントなども、パイプライン内でアップロード済みのURLを指定することで、リリースアセットとして添付できます。
自動リリースの実行
この設定が完了すれば、リリースを実行するために必要なのは、バージョン付けのルールに従ったタグをリポジトリにプッシュすることだけです。CLIからタグをプッシュすることもできますが、ここではGitLabのUIを使って、mainブランチにタグを作成する例をご紹介します。タグを作成するには、サイドバーからコード > タグ > 新しいタグを選択します。
タグの作成が完了すると、パイプラインの実行が開始されます。 GitLabのChangelog APIが、今回のリリースと前回のリリースの間に行われた変更をすべて含むリリースノートをMarkdown形式で自動的に生成します。 以下は、この例で生成されたMarkdownの出力結果です。
## 2.0.0 (2023-08-25)
### added (1 change)
- [Add ChatBot](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo@0c3601a45af617c5481322bfce4d71db1f911b02) ([merge request](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo!4))
### removed (1 change)
- [Remove Unused Features](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo@463d453c5ae0f4fc611ea969e5442e3298bf0d8a) ([merge request](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo!3))
ご覧のとおり、GitLabはgitのコミットトレーラーをもとに、リリースノートのエントリを自動で抽出しています。さらに、変更の詳細やディスカッションが確認できるよう、マージリクエストへのリンクも付けられています。
そしてこちらが、最終的に作成されたリリースです。
変更履歴の作成
次に、変更履歴（すべてのリリースノートをまとめた履歴）を更新します。これを行うには、先ほど使用したChangelog APIエンドポイントに対して、POSTリクエストを送ります。
必要であれば、この処理をリリースパイプラインの一部として実行することも可能です。たとえば、prepareジョブのscriptセクションに以下の内容を追加します。
'curl -H "PRIVATE-TOKEN: $CI_API_TOKEN" -X POST "$CI_API_V4_URL/projects/$CI_PROJECT_ID/repository/changelog?version=$CI_COMMIT_TAG"
この処理は実際にリポジトリを変更する点にご注意ください。 具体的には、最新のリリースノートをCHANGELOG.mdファイルに追加するためのコミットが作成されます。
これですべて完了です！gitが提供する豊富な履歴情報と、便利なコミットトレーラーを活用することで、GitLabの強力なAPIとCI/CDパイプラインを使って、リリースプロセスとリリースノートの生成を自動化できます。
この記事で使用したプロジェクトを実際に確認したい場合は、こちらのリンクからご覧いただけます。