この記事は、 MIXI DEVELOPERS Advent Calendar 2025 の 5 日目の記事です。
みなさん、Terraform Module を使ってますか？Module、いいですよね。複雑怪奇な Terraform コードを隠蔽してくれる、とても便利なやつです（ぇ
ところで、作成した Terraform Module、どう管理していますか？Module のバージョンをちゃんと管理している人……意外と少ないんじゃないでしょうか。
少し前に、Terraform Module のバージョン管理について、AWS と Google Cloud の公式 Module を調べてみたことがあります。どちらも「PR をマージするたびに自動でバージョンが更新される」という仕組みが整っていて、非常に便利そうでした。
これ、導入できたら嬉しくないですか？嬉しいですよね。そう、嬉しいんです。
というわけで今回は、AWS の公式 Module を例に、バージョン管理を自動化する仕組みを解説していきます。
バージョン管理における基本的な考え方
AWS の公式 Terraform Module は、以下のようなシンプルな仕組みで更新されています。
- PR をマージすると自動でバージョンが上がる
- バージョン番号は 0.0.0 の形式で、どの数字を上げるかは PR のタイトルにつくプレフィックスで決まる
これは Conventional Commits と Semantic Versioning という２つの考え方に基づいています。
Conventional Commits
Conventional Commits とは大まかに以下のような考え方です。
- コミットメッセージに「どんな変更か」を体系的に書くルール
- 基本形式は以下
<type>[optional scope]: <description> - type には
fixやfeatなどがある - 破壊的変更がある場合は
fix!のように!を付ける
Semantic Versioning
Semantic Versioning は、大まかに以下のような考え方です。
- バージョン番号の付け方を決めるルール
- 0.0.0 形式で、左から major、minor、patch
- 変更内容に応じて番号を increment する
- major … 後方互換性のない変更
- minor … 後方互換性のある新機能
- patch … 後方互換性のあるバグ修正
これらを組み合わせ、AWS の Terraform Module では以下のように自動バージョンアップを行っています。
- PR タイトルが
fix:などの type の場合 → patch を上げる - PR タイトルが
feat:の場合 → minor を上げる - PR タイトルに
feat!:など破壊的変更を示す!がついている場合 → major を上げる
AWS の Module はこれらのルールを GitHub Actions で実装し、バージョン管理を極限まで省力化しています。
AWS の Terraform Module の GitHub Actions
実際の GitHub Actions を見てみましょう。一例として AWS VPC Module を取り上げます。
こちらの .github/workflows には、バージョン管理に関わるファイルがいくつかあります。
それぞれの役割は以下のとおりです。
- pr-title.yml
- PR タイトルに Conventional Commits に基づいたプレフィックスがついているかをチェックするもの
- pre-commit.yml
- 不要ファイル削除や互換性チェックなど、PR 作成時の前処理
- release.yml
- PR マージ時に release を作成し、バージョン番号や CHANGELOG を自動生成
ここからはそれぞれ詳しく見ていきます。
pr-title.yml
中身は以下のようになっています。
使用しているのは以下の Action です。
これは PR タイトルが Conventional Commits に従っているかをチェックするものです。Conventional Commits のルールでは、以下のような書き方でした。（再掲）
<type>[optional scope]: <description>
AWS の Module では scope はほぼ使われておらず、以下の type を基本的に使用しているようです。
- fix
- feat
- docs
- ci
- chore
この GitHub Actions により、AWS の Terraform Module の PR のタイトルは、全てこの Type のプレフィックスがついています。
pre-commit.yml
こちらの中身は以下のようになっています。
主に以下を行っています。
- versions.tf があるディレクトリの洗い出し
- 洗い出したディレクトリごとに、サポートできる Terraform の最新バージョンと最低バージョンを確認
- https://github.com/clowdhaus/terraform-min-max の action を利用
- 最新・最低バージョンで、以下を実行
- pre-commit や Terraform 関連ツールのセットアップ
- https://github.com/clowdhaus/terraform-composite-actions の pre-commit の action を利用
- terraform fmt や tflint など Terraform 関連の処理の実行
- EOF や空白などの細かい修正
- pre-commit や Terraform 関連ツールのセットアップ
ここで活躍しているのが pre-commmit というツールです。
pre-commit は、 .pre-commit-config.yaml に書いてある設定に基づいて、様々なチェック・整形処理を自動化できます。プラグインという形で、様々な処理を簡単に追加することができます。
AWS の Module では、以下のような処理を行っていることが分かります。
- Terraform 関連の処理の実行
- https://github.com/antonbabenko/pre-commit-terraform のプラグインを利用
- terraform fmt
- terraform-docs
- tflint
- terraform validate
- その他細かい処理
- https://github.com/pre-commit/pre-commit-hooks のプラグインを利用
- マージのコンフリクトの確認
- EOF の修正
- Markdown の末尾の空白を削除
この設定により、Terraform のバージョン互換チェックから細かい修正まで、全て自動で完結します。
release.yml
こちらの中身は以下のようになっています。
ここはとてもシンプルで、以下の Action を使っています。
これは Node 製ツール semantic-release によって動作します。
このツールは、.releaserc.json に書いてある設定に基づいて、リリースに関連する様々な処理を実行してくれます。このツールも、プラグインという形で、必要な処理を簡単に追加することができます。
AWS の Terraform Module では、以下のようなプラグインが設定されていました。
- semantic-release/commit-analyzer
- こちらはコミット内容を確認し、次のバージョン番号を決定するもの
- type や破壊的変更の有無に応じて、major、minor、patch バージョンのどれかを上げてくれる
- semantic-release/release-notes-generator
- こちらは書いてあるPR の内容から、リリースノートを自動で生成してくれる
- semantic-release/github
- こちらは、GitHub の release を作成してくれる。また関連する PR や issue にコメントをしてくれる
- semantic-release/changelog
- こちらは CHANGELOG.md を生成してくれる
- semantic-release/git
- こちらは生成した CHANGELOG などのファイルをコミットしてくれる
これらにより、PR タイトル → バージョン判定 → リリース作成 → CHANGELOG 更新という一連の流れが完全自動化されます。
マージコミットの設定
最後に、これらの GitHub Actions を正しく動かすための重要なポイントがあります。それがマージコミットの設定です。
semantic-release の commit-analyzer は、マージコミットを読みません。なぜなら、マージコミットは Merge pull request ... の形式で Conventional Commits に従っていないからです。
そのため AWS のリポジトリでは、
デフォルトのマージ方法を squash にし、コミットメッセージを PR タイトルにする
という設定がされています。
Squash Merge なら、複数コミットを１つにまとめ、そのコミットメッセージに PR タイトル（= Conventional Commit 形式） を使用できます。
設定箇所は、リポジトリの settings > General の Pull Requests の項目にあります。
この設定により、semantic-release が問題なく PR タイトルからバージョンを判定できるようになります。
まとめ
AWS の Terraform Module では、以下のファイルによって、バージョン管理が完全自動化されていることがわかりました。
├── .pre-commit-config.yaml
├── .releaserc.json
└── .github
└── workflows
├── pr-title.yml
├── pre-commit.yml
└── release.yml
これらのツールを利用して、みなさまも Terraform Module のバージョン管理をしてみてはいかがでしょうか？
Discussion