こんにちは。テクマトリックスの橘です。
Jenkinsのマルチブランチパイプラインを運用していると、「READMEや設定ファイルを少し修正しただけなのに、CIが走ってしまった」という経験はないでしょうか。ビルドやテストに時間がかかる環境では、こうした不要なビルドの積み重ねが、エージェントリソースの消費や通知ノイズの増加につながります。
本記事では、変更されたファイルの内容に応じてビルドのキャンセル・許可を制御できる Pipeline: Multibranch build strategy extension プラグインをご紹介します。
このプラグインはGitリポジトリを対象とした環境でのみ動作します。
Subversionをお使いの場合は本プラグインをご利用いただけませんので、あらかじめご了承ください。
目次
Pipeline: Multibranch build strategy extensionとは
このプラグインは、マルチブランチパイプラインのジョブに対して、「どのような変更があったときにビルドを実行するか」 を細かく制御するための追加ストラテジーを提供するものです。
通常のマルチブランチパイプラインでは、ブランチに対してコミットがプッシュされるたびにビルドがトリガーされます。このプラグインを利用することで、たとえば「ドキュメントファイルの変更だけのコミットではビルドしない」「特定のコミットメッセージが含まれている場合はビルドをスキップする」といった制御が可能になります。
動作環境・前提条件
本プラグインを利用するにあたって、以下の点をあらかじめご確認ください。
| 項目 | 内容 |
|---|---|
| Jenkinsバージョン | 2.504.3 以上 |
| 対応SCM | Git のみ（Subversion・Mercurial 等は非対応） |
| 前提プラグイン | Git プラグイン、Branch API プラグイン |
プラグインの依存関係としてGitプラグインのみが含まれており、Subversionプラグインには対応していません。現在SubversionでCI環境を運用されている場合は、Gitへの移行を検討したうえで本プラグインの導入をご検討ください。
インストール方法
Jenkinsの管理画面から、以下の手順でインストールできます。
- Manage Jenkins > Plugins > Available plugins を開く
- 検索欄に
multibranch build strategyと入力 - Pipeline: Multibranch build strategy extension にチェックを入れ、Install をクリック
インストール後、マルチブランチパイプラインジョブの設定画面に Build strategies セクションが追加されます。
提供されるストラテジーの紹介
Build strategies セクションの Add ボタンをクリックすると、以下のストラテジー(設定方針)が選択できます。
Accept build by included regions strategy
指定したファイルパターンへの変更が含まれているコミットの場合のみ、ビルドを許可するストラテジーです。パターンはテキストエリアに直接記述します。
「このディレクトリのファイルが変わったときだけビルドしたい」という用途に向いています。
たとえば、以下のように Ant パターンで記載します。
# 例：src/main/java 配下のJavaファイルが変更されたコミットのみビルド
src/main/java/**/*.javaAccept build by included regions strategy defined in file
上記と同じ動作ですが、パターンをテキストエリアに直接書く代わりに、リポジトリ内のファイルにまとめて記述し、そのファイルパスを指定する方式です。パターン数が多い場合や、パターン自体をコードと一緒にバージョン管理したい場合に便利です。
Cancel build by excluded regions strategy
指定したファイルパターンへの変更のみが含まれるコミットの場合、ビルドをキャンセルするストラテジーです。パターンはテキストエリアに直接記述します。
「ドキュメントや設定ファイルだけの変更ではビルドをスキップしたい」という用途に向いています。
# 例：ドキュメント類を対象外とする
docs/**
**/*.md
# 例：Web静的ファイルを対象外とする
src/main/web/**/*.html
src/main/web/**/*.css
# 例：CI設定ファイルを対象外とする
JenkinsfileCancel build by excluded regions strategy defined in file
上記と同じ動作ですが、パターンをリポジトリ内のファイルで管理する方式です。
Cancel build by excluded commit messages strategy
コミットメッセージに指定したフレーズ（Java正規表現）が含まれている場合に、ビルドをキャンセルするストラテジーです。リリースツールや自動コミットによる不要なビルドをスキップしたい場合に使います。
例：[ci-skip] というフレーズが含まれる場合にビルドをキャンセル
.*\[ci\-skip\].*
# 例：[maven-release-plugin] というフレーズが含まれる場合にビルドをキャンセル
.*\[maven\-release\-plugin\].*Cancel ci by ignore file strategy（deprecated）
リポジトリ内の特定ファイルの有無によってビルドをキャンセルするストラテジーです。現在は非推奨（deprecated） となっており、新規利用は推奨されません。
CancelとAcceptの使い分け
| Cancel（除外） | Accept（包含） | |
|---|---|---|
| 考え方 | 除外したいファイルを指定する | ビルド対象のファイルを指定する |
| 向いているケース | 除外対象が少数で明確な場合 | ビルド対象が限定的で明確な場合 |
| パターン漏れ時の挙動 | 意図せずビルドが走る | 意図せずビルドがスキップされる |
どちらを選ぶかはプロジェクトの構成によりますが、「基本的にビルドを走らせたい、一部だけスキップしたい」という場合は Cancel、「特定の成果物に関係する変更だけビルドしたい」という場合は Accept が向いています。
実際に設定してみた
検証環境
| ツール | バージョン |
|---|---|
| Jenkins | 2.555.2 |
| Pipeline: Multibranch build strategy extension | 71.va_359eeb_a_a_6f0 |
| GitLab(Gitリポジトリ) | ce:17.8.2-ce.0 |
ユースケース：README.md、.gitignore、.htmlファイルの変更ではビルドを走らせたくない
ソースコードとは直接関係のないファイルの変更でビルドが走ることを防ぐため、Cancel build by excluded regions strategy を使って設定します。
設定手順
- マルチブランチパイプラインジョブの設定画面を開く
- Branch Sources セクション内の Build strategies まで下にスクロールする
- Add ボタンをクリックし、Cancel build by excluded regions strategy を選択する
- テキストエリアに除外したいファイルパターンを入力する
- 今回は、
README.md・.gitignore・.htmlファイルを対象外に設定
- 今回は、
動作確認
設定後、以下の2パターンでコミットを作成し、動作を確認しました。
ケース1：README.mdのみ変更してプッシュ
ビルドのジョブ履歴には記録されず、システムログには除外パターンに該当し、ビルドをスキップしたことが記録されていました。
ケース2：ソースコードとREADME.mdを変更してプッシュ
ソースコードファイルへの変更が含まれているため、ビルドは正常に実行されました。なお、直前のコミット（ケース1：README.mdのみ変更してプッシュ）はビルドがスキップされていましたが、今回のビルドではそのコミットも含めてビルドが実行されていることが確認できます。
README.md への変更が含まれていても、他のファイルへの変更があればビルドはキャンセルされません。この点は Cancel 系ストラテジーの重要な動作として押さえておく必要があります。
使ってみての感想・注意点
よかった点
設定がシンプルで、Antパターンの記述に慣れていれば迷わずに設定できました。また、この記事内では紹介していませんが、ストラテジーは複数追加することができるため、たとえば 「Cancel build by excluded regions strategy」（除外リージョン）と「Cancel build by excluded commit messages strategy」（コミットメッセージ）を組み合わせるといった構成も可能です。
気になった点・ハマりどころ
Subversionに対応していない
実は、このプラグインを調査したのは、特定のフォルダの更新時のみビルドを走らせたい、とお客様からご相談をいただいたのがきっかけでした。そちらのお客様ではSubversionを利用されており、弊社内に検証環境を立ち上げ、何度も設定をしてみたのですが、うまく動作せず、調査の結果、本プラグインがGitしかサポートしていないということが分かりました。日本ではまだまだSubversionを利用されている開発現場が多いことを考えると、少し残念です。
ちなみに、上記のお客様はリポジトリ内の一つのフォルダ以下にビルドに必要なソースコード等が集約されていたため、そのフォルダをJenkinsのスキャン対象とすることで、ご要望を満たすことができました。
キャンセルされたジョブはシステムログでしかわからない
これはこのプラグインの仕様を私が誤解していたから感じただけではあるのですが、「ジョブがキューに載ってから、キャンセルか実行かの判断をされ、キャンセルされたジョブは該当ブランチのジョブの履歴にCancelledというステータスで表示される」と思っていたため、ケース1：README.mdのみ変更してプッシュを実行後、ひたすらジョブが表示されるのを待つものの、一向に表示されず、システムログを見て初めて、裏でキャンセルされていたことに気づきました。ジョブの履歴に余計なものが表示されないというこの仕様が適切だと思いますので、私が気づけなかったというだけです。
Cancel と Accept を同時に設定した場合の挙動に注意
前述の通り、複数のストラテジーを追加することができるのですが、複数のストラテジーを追加した場合、いずれかのストラテジーがビルドをキャンセルと判断した時点でビルドはキャンセルされます。CancelとAcceptを混在させると意図しない挙動になる場合があるため、基本的にはどちらか一方の方針に統一することをおすすめします。
まとめ
本記事では、Pipeline: Multibranch build strategy extensionプラグインを使って、変更されたファイルの内容に応じてビルドを制御する方法をご紹介しました。各ストラテジーのユースケースを以下にまとめます。
| ストラテジー | こんな時に使う |
|---|---|
| Accept by included regions | 特定ディレクトリ配下など、対象ファイルの変更があったときだけビルドしたい |
| Accept by included regions defined in file | 上記と同じ。パターンをリポジトリ内ファイルでバージョン管理したい |
| Cancel by excluded regions | ドキュメントや静的ファイルなど、一部ファイルの変更のみの場合はビルドをスキップしたい |
| Cancel by excluded regions defined in file | 上記と同じ。パターンをリポジトリ内ファイルでバージョン管理したい |
| Cancel by excluded commit messages | リリースツールや自動コミットによるビルドをスキップしたい |
| Cancel ci by ignore file | 非推奨のため新規利用は避ける |
不要なビルドを減らすことは、エージェントリソースの有効活用だけでなく、開発者が受け取る通知のノイズ削減にもつながります。ぜひ活用してみてください。
弊社の開発基盤ソリューションチームでは、JenkinsやGitHub Actionsを利用したCI/CD環境の構築・改善をご支援しています。
現在のCI環境の課題や改善のご相談がございましたら、お気軽にお問い合わせください。
