Jenkinsから送信されるメールをカスタマイズする

みなさんこんにちは。@ryuzeeです。

Jenkinsから送信されるメールをカスタマイズするにはどうしたら良いでしょうか？

答えはEmail-extプラグイン(https://wiki.jenkins-ci.org/display/JENKINS/Email-ext+plugin)を使うのですが、設定の方法などを書いておくことにします。

Email-extプラグインとは

Jenkinsが送信するメールをカスタマイズするプラグインで、送信するメールのタイトルや本文、いつ送信するか、誰に送信するか等をカスタマイズすることができます。またビルド失敗、テスト失敗、ビルドの正常への復帰などの状況に応じて送信するメールを個別にカスタマイズすることが可能です。 2012年1月現在バージョンは2.16です。

インストール

これはいつもの通りです。 Jenkinsの管理→プラグインの管理と遷移して、“Jenkins Email Extension Plugin"を選択してインストールします。もしくはjenkins-cli.jar経由でも同じです。

設定方法

設定は、各プロジェクト共通の設定と、プロジェクト固有の設定に分けて行います。なお共通設定を行っていても、各プロジェクト側の設定で値を上書きすることができます。

それぞれの項目について説明します。

「E-mail通知の設定を上書き」チェックを入れることで従来のメールの代わりにこちらを使います
「SMTPサーバ」送信に利用するSMTPサーバを設定します
「デフォルトE-mailのサフィックス」@以降のデフォルト値を設定します
「管理者のメールアドレス」送信元のメールアドレスになるので設定します
「Jenkins URL」メール内に記載されるJenkinsのURLを設定します（デフォルト値が入っています）
SMTP認証などが必要な場合は「高度な設定」で行います
「デフォルトコンテンツ形式」プレーンテキスト形式かhtmlメール形式のいずれかが選択できます
「Use List-ID Email Header」メーリングリスト用にメールヘッダにList-IDをセットできます
「Add ‘Precedence: bulk’ Email Header」大量メールを示すBulkヘッダをメールヘッダにセットできます
「Default Recipients」デフォルトでの受信者をセットできるように見えますが、**このフィールドは現在動作しません。過去の名残で残っているので値を設定しても保存もされません。**デフォルトでの送信先をシステム全体で設定したい場合は環境変数を利用します（後述）
「デフォルトサブジェクト」メールのデフォルトのタイトルを設定できます。日本語も利用できます
「Maximum Attachment Size」添付ファイルの最大サイズを設定します
「デフォルトコンテンツ」送信するメールの本文を指定します。利用可能なトークン(置き換え用の文字列)は後述します

なお、Default Recipientsの代わりにメール受信者のデフォルト値を設定するためには、図のようにGlobal propertiesで環境変数を指定します。この環境変数は ${ENV, var=“default_email”}のように呼び出すことができます。

利用可能なトークン

${BUILD_LOG, maxLines, escapeHtml}
ビルドログ

${BUILD_LOG_REGEX, regex, linesBefore, linesAfter, maxMatches, showTruncatedLines, substText, escapeHtml, matchedLineHtmlStyle}
ビルドログを正規表現で抽出

${BUILD_NUMBER}
ビルド番号

${BUILD_STATUS}
ビルドのステータス(成功、失敗など)

${BUILD_URL}
ビルドのURL

${CHANGES, showPaths, format, pathFormat}
SCMにおける前回の変更からの変更点

${CHANGES_SINCE_LAST_SUCCESS, reverse, format, showPaths, changesFormat, pathFormat}
最後に成功したビルド以降の変更点

${CHANGES_SINCE_LAST_UNSTABLE, reverse, format, showPaths, changesFormat, pathFormat}
最後にビルドが不安定になって以降の変更点

${ENV, var}
環境変数を表示する。${ENV, var="変数名"}と指定する

${FAILED_TESTS}
失敗したテストの情報を表示する

${JENKINS_URL}
JenkinsのURL

${HUDSON_URL}
HudsonのURL。非推奨。

${PROJECT_NAME}
プロジェクト名

${PROJECT_URL}
プロジェクトのURL

${SVN_REVISION}
Subversionのリビジョン番号

${CAUSE}
ビルド失敗の理由

${JELLY_SCRIPT, template}
メールのテンプレートの読み込み。デフォルトでは${JELLY_SCRIPT,template="html"}と${JELLY_SCRIPT,template="text"}が用意されている。自分で作成する場合は、$JENKINS_HOME/email-templatesに配置する。

${FILE, path}
指定したファイルをインクルードする

${TEST_COUNTS, var}
テストの数

${SCRIPT, script, template, init}
JSR223を利用したカスタムメッセージを挿入する。

テンプレート例

送信するメールのテンプレートの一例を以下に記載します。 html形式で送信したい場合は、ほとんどの場合トークンをpreタグで囲みつつその他の項目をhtmlで書くか、もしくはJellyでスクリプトを書くかのどちらかになると思われます。

$PROJECT_NAME - Build # $BUILD_NUMBER - $BUILD_STATUS:

以下のURLを確認してください。
----------------------------------------
$BUILD_URL to view the results.

失敗したテスト
----------------------------------------
${FAILED_TESTS}

前回の成功ビルド以降に更新されたファイル
----------------------------------------
${CHANGES_SINCE_LAST_SUCCESS}

ビルドログ
----------------------------------------
${BUILD_LOG}

プロジェクト側の設定

次にプロジェクト側の設定を行います。

プロジェクト側の設定も共通設定とほぼ同じですが1点注意で、グローバル受信者リストの箇所にデフォルトで入っている$DEFAULT_RECIPIENTSの値には値が含まれません(仕様)ので、${ENV, var=“default_email”}に置き換えてください。またDEFAULT_SUBJECTおよびDEFAULT_CONTENTというトークンが利用可能です。これらの値は共通設定で行ったタイトルおよび本文になります。

この画面の「トリガーを追加」のプルダウンを選択することで、発生したイベントに応じてメールの送信者や本文を定義することができます。 Unstable、Not built、Failure、Fixedあたりでは、送信したいメッセージが変わってくるはずですのでそれぞれ定義します。

以上が終わったら保存して設定は完了です。