注：本文由Jdonee投遞

來源：http://www.juvenxu.com/2011/05/18/hudson-email-ext/

簡(jiǎn)述

眾所周知，Jenkins(Hudson)默認(rèn)提供了一個(gè)郵件通知，能在構(gòu)建失敗、構(gòu)建不穩(wěn)定等狀態(tài)后發(fā)送郵件。但是它本身有很多局限性，比如它的郵件通知無法提供詳細(xì)的郵件內(nèi)容、無法定義發(fā)送郵件的格式、無法定義靈活的郵件接收配置等等。在這樣的情況下，我們找到了Jenkins Email Extension Plugin。該插件能允許你自定義郵件通知的方方面面，比如在發(fā)送郵件時(shí)你可以自定義發(fā)送給誰，發(fā)送具體什么內(nèi)容等等。本文不會(huì)告訴你如何安裝該插件，關(guān)于插件的安裝請(qǐng)參考這里。

功能概要

該插件擴(kuò)展了Hudson構(gòu)建默認(rèn)的郵件通知功能，并賦予你更多更靈活的控制。它能在如下三塊區(qū)域來自定義：

• Triggers -指定發(fā)送一封郵件通知應(yīng)有的前置條件。
• Content - 指定每封觸發(fā)郵件的標(biāo)題和正文的內(nèi)容。
• Recipients -.指定一封郵件觸發(fā)后發(fā)送給誰來接收(郵件)。

配置

它主要包含兩個(gè)部分：基本配置和項(xiàng)目配置。

公共配置

當(dāng)然，在一個(gè)項(xiàng)目中應(yīng)用email-ext插件之前，您必須做一些公共的配置?，F(xiàn)在先跳轉(zhuǎn)到Hudson的“系統(tǒng)配置”頁面，如下圖：

找到標(biāo)題為“Extended E-mail Notification”的片段，你就能配置一些公共的 email-ext屬性。這些屬性必須匹配你SMTP郵件服務(wù)器的設(shè)置。這一節(jié)不僅能配置成Hudson原有郵件通知的鏡像(雖然有很多配置是一樣的，但 這是個(gè)不同的擴(kuò)展點(diǎn))，而且還增加了一些額外的功能。輸入框中名為 Default Subject 和 Default Content 的項(xiàng)允許你在公共級(jí)別配置郵件的內(nèi)容。這樣做的話，可以使您為所有的項(xiàng)目按您的需求做更好的、更簡(jiǎn)單的配置。如下圖。

根據(jù)幫助文檔，我們可以了解到一些公共屬性，下面我解釋一下常用的屬性。
屬性詳解：

1. Override Global Settings
   如果不選，該插件將使用默認(rèn)的E-mail Notification通知選項(xiàng)。反之，您可以通過指定不同于( 默認(rèn)選項(xiàng))的設(shè)置來進(jìn)行覆蓋。
2. Default Content Type
   指定構(gòu)建后發(fā)送郵件內(nèi)容的類型，有Text和HTML兩種.
3. Use List-ID Email Header
   為所有的郵件設(shè)置一個(gè)List-ID的郵件信頭，這樣你就可以在郵件客戶端使用過濾。它也能阻止郵件發(fā)件人大部分的自動(dòng)回復(fù)(諸如離開辦公室、休假等 等)。你可以使用你習(xí)慣的任何名稱或者ID號(hào)，但是他們必須符合如下其中一種格式(真實(shí)的ID必須要包含在<和>標(biāo)記里)：
   <ci-notifications.company.org>
   Build Notifications <ci-notifications.company.org>
   “Build Notifications” <ci-notifications.company.org>
   關(guān)于更詳細(xì)的List-ID說明請(qǐng)參閱RFC-2919.
4. Default Subject
   自定義郵件通知的默認(rèn)主題名稱。該插件能在郵件的主題字段中替換一些令牌，這樣你就可以從構(gòu)建中包含指定的輸出信息。
5. Default Content
   自定義郵件通知的默認(rèn)內(nèi)容主體。該插件能在郵件的內(nèi)容主體中替換一些令牌，這樣你就可以從構(gòu)建中包含指定的輸出信息。
6. Content Token Reference[公共配置]
   所有的參數(shù)都是可選的，每個(gè)令牌的參數(shù)可以如下表示，字符串類型使用name=“value”，而布爾型和數(shù)字型使用name=value。如果{和}標(biāo)記里面沒有參數(shù)，則不會(huì)被解析。
   示例：$TOKEN, ${TOKEN}, ${TOKEN, count=100}, ${ENV, var=”PATH”}

可用令牌

• ${BUILD_LOG, maxLines, escapeHtml} -顯示最終構(gòu)建日志。
  • maxLines – 顯示該日志最多顯示的行數(shù)，默認(rèn)250行。
  • escapeHtml -如果為true，格式化HTML。默認(rèn)false。
• ${BUILD_LOG_REGEX, regex, linesBefore, linesAfter, maxMatches, showTruncatedLines, substText, escapeHtml, matchedLineHtmlStyle} -按正則表達(dá)式匹配顯示構(gòu)建日志的行數(shù)。
  • 匹配符合該正則表達(dá)式的行數(shù)。參閱java.util.regex.Pattern，默認(rèn)“(?i)\b(error|exception|fatal|fail(ed|ure)|un(defined|resolved))\b”。
  • linesBefore -包含在匹配行之前的行編號(hào)。行數(shù)會(huì)與當(dāng)前的另一個(gè)行匹配或者linesAfter重疊，默認(rèn)0。
  • linesAfter -包含在匹配行之后的行編號(hào)。行數(shù)會(huì)與當(dāng)前的另一個(gè)行匹配或者linesBefore重疊，默認(rèn)0。
  • maxMatches -匹配的最大數(shù)量，如果為0，則包含所有匹配。默認(rèn)為0。
  • showTruncatedLines -如果為true，包含[...truncated ### lines...]行。默認(rèn)為true。
  • substText -如果非空，把這部分文字插入該郵件，而不是整行。默認(rèn)為空。
  • escapeHtml -如果為true，格式化HTML。默認(rèn)false。
  • matchedLineHtmlStyle -如果非空，輸出HTML。匹配的行數(shù)將變?yōu)?lt;b style=”your-style-value”> html escaped matched line </b>格式。默認(rèn)為空。
• ${BUILD_NUMBER} -顯示當(dāng)前構(gòu)建的編號(hào)。
• ${BUILD_STATUS} -顯示當(dāng)前構(gòu)建的狀態(tài)(失敗、成功等等)
• ${BUILD_URL} -顯示當(dāng)前構(gòu)建的URL地址。
• ${CHANGES, showPaths, format, pathFormat} -顯示上一次構(gòu)建之后的變化。
  • showPaths – 如果為 true,顯示提交修改后的地址。默認(rèn)false。
  • format – 遍歷提交信息，一個(gè)包含%X的字符串，其中%a表示作者，%d表示日期，%m表示消息，%p表示路徑，%r表示版本。注意，并不是所有的版本系統(tǒng)都支持%d和%r。如果指定showPaths將被忽略。默認(rèn)“[%a] %m\n”。
  • pathFormat -一個(gè)包含“%p”的字符串，用來標(biāo)示怎么打印字符串。
• ${CHANGES_SINCE_LAST_SUCCESS, reverse, format, showPaths, changesFormat, pathFormat} -顯示上一次成功構(gòu)建之后的變化。
  • reverse -在頂部標(biāo)示新近的構(gòu)建。默認(rèn)false。
  • format -遍歷構(gòu)建信息，一個(gè)包含%X的字符串，其中%c為所有的改變，%n為構(gòu)建編號(hào)。默認(rèn)”Changes for Build #%n\n%c\n”。
  • showPaths, changesFormat, pathFormat – 分別定義如${CHANGES}的showPaths、format和pathFormat參數(shù)。
• ${CHANGES_SINCE_LAST_UNSTABLE, reverse, format, showPaths, changesFormat, pathFormat} -顯示顯示上一次不穩(wěn)固或者成功的構(gòu)建之后的變化。
  • reverse -在頂部標(biāo)示新近的構(gòu)建。默認(rèn)false。
  • format -遍歷構(gòu)建信息，一個(gè)包含%X的字符串，其中%c為所有的改變，%n為構(gòu)建編號(hào)。默認(rèn)”Changes for Build #%n\n%c\n”。
  • showPaths, changesFormat, pathFormat -分別定義如${CHANGES}的showPaths、format和pathFormat參數(shù)。
• ${ENV, var} – 顯示一個(gè)環(huán)境變量。
  • var – 顯示該環(huán)境變量的名稱。如果為空，顯示所有，默認(rèn)為空。
• ${FAILED_TESTS} -如果有失敗的測(cè)試，顯示這些失敗的單元測(cè)試信息。
• ${JENKINS_URL} -顯示Jenkins服務(wù)器的地址。(你能在“系統(tǒng)配置”頁改變它)。
• ${HUDSON_URL} -不推薦，請(qǐng)使用$JENKINS_URL
• ${PROJECT_NAME} -顯示項(xiàng)目的名稱。
• ${PROJECT_URL} -顯示項(xiàng)目的URL。
• ${SVN_REVISION} -顯示SVN的版本號(hào)。
• ${CAUSE} -顯示誰、通過什么渠道觸發(fā)這次構(gòu)建。
• ${JELLY_SCRIPT, template} -從一個(gè)Jelly腳本模板中自定義消息內(nèi)容。有兩種模板可供配置：HTML和TEXT。你可以在$JENKINS_HOME/email-templates下自定義替換它。當(dāng)使用自動(dòng)義模板時(shí)，”template”參數(shù)的名稱不包含“.jelly”。
  • template -模板名稱，默認(rèn)”html”。
• ${FILE, path} -包含一個(gè)指定文件的內(nèi)容
  • path -文件路徑，注意，是工作區(qū)目錄的相對(duì)路徑。
• ${TEST_COUNTS, var} -顯示測(cè)試的數(shù)量。
  • var – 默認(rèn)“total”。
    • total -所有測(cè)試的數(shù)量。
    • fail -失敗測(cè)試的數(shù)量。
    • skip -跳過測(cè)試的數(shù)量。

項(xiàng)目配置

要想在一個(gè)項(xiàng)目中使用email-ext插件，你首先必須在項(xiàng)目配置頁激活它。在”Post-build Actions”選項(xiàng)中勾選”Editable Email Notification”標(biāo)簽。

項(xiàng)目基本配置

當(dāng)插件激活后你就能編輯如下三個(gè)字段：

• Global Recipient List -這是一個(gè)以逗號(hào)(或者空格)分隔的可接受郵件的郵箱地址列表。允許您為每封郵件指定單獨(dú)的列表。
• Default Subject -允許你配置令牌，這樣就可以在項(xiàng)目中更容易地配置所有郵件的主題。
• Default Content -跟 Default Subject的作用一樣，但是是把主題替換內(nèi)容主體。

項(xiàng)目高級(jí)配置

要查看插件的高級(jí)配置，請(qǐng)點(diǎn)擊”Advanced”按鈕。該選項(xiàng)允許您各種類型的郵件觸發(fā)器指定接收者。默認(rèn)情況下，唯一使用的觸發(fā)器配置 是”Failure”觸發(fā)器。要增加更多的觸發(fā)器，選擇“Add a Trigger”旁邊下拉列表中的類型，它會(huì)增加到控件上面的列表中。一旦你增加了一個(gè)觸發(fā)器，你就可以對(duì)它做一些選擇。如果你點(diǎn)擊一個(gè)觸發(fā)器旁邊 的”?”號(hào)，它將告訴你你在什么前置條件中來觸發(fā)郵件發(fā)送。如下圖。

• Send to Recipient List -如果勾選，郵件將發(fā)送到”Global Recipient List”中的所有郵件地址。
• Send to Committers -該郵件會(huì)發(fā)給上次構(gòu)建時(shí)檢查過代碼的人員，該插件會(huì)基于提交者的ID和追加Jenkins配置頁面的(default email suffix)默認(rèn)郵件后綴來生成一個(gè)郵件地址。譬如，上次提交代碼的人是”first.last”， 默認(rèn)的電子郵件后綴為“@somewhere.com”，那么電子郵件將被發(fā)送到“first.last@ somewhere.com”。
• Send To Requester -如果勾選，郵件將發(fā)送給構(gòu)建觸發(fā)者。
• Include Culprits -如果勾選，而且 “Send To Committers”勾選，郵件將包含最后成功構(gòu)建的提交者。
• More Configuration -通過單擊”+(expand)”鏈接您能為每個(gè)郵件觸發(fā)器作更多單獨(dú)的設(shè)置。
  • Recipient List -這是一個(gè)以逗號(hào)(或者空格)分隔的可接受郵件的郵箱地址列表。如果觸發(fā)就發(fā)送郵件到該列表。該列表會(huì)追加在”Global Recipient List”里。
  • Subject – 指定選擇郵件的主題。注意：高級(jí)選項(xiàng)中的郵件觸發(fā)器類型可覆蓋對(duì)它的配置。
  • Content -指定選擇郵件的內(nèi)容主體。注意：高級(jí)選項(xiàng)中的郵件觸發(fā)器類型可覆蓋對(duì)它的配置。
• Remove -通過單擊指定觸發(fā)器當(dāng)前行的”Delete”按鈕，你可以刪除該觸發(fā)器。

項(xiàng)目郵件令牌

email-ext插件使用令牌來允許動(dòng)態(tài)數(shù)據(jù)插入到郵件的主題和內(nèi)容主體中。令牌是 一個(gè)以$(美元符號(hào))開始，并以空格結(jié)束的字符串。當(dāng)一個(gè)郵件觸發(fā)時(shí)，主題和內(nèi)容主體字段的所有令牌都會(huì)通過真實(shí)的值動(dòng)態(tài)地替換。同樣，令牌中的“值”能 包含其它的令牌，那將被替換成真實(shí)的內(nèi)容。比如， $DEFAULT_SUBJECT令牌能通過從公共配置頁面的Default Subject字段中的文本(或者其它令牌)替換。同理， $PROJECT_DEFAULT_SUBJECT令牌也能通過項(xiàng)目配置頁面的Default Subject 字段中值替換。

一旦你的項(xiàng)目中激活email-ext插件，它會(huì)使用默認(rèn)值設(shè)置郵件的內(nèi)容字段。項(xiàng)目配置頁的默認(rèn)主題和主體內(nèi)容字段分別對(duì)應(yīng)的是 DEFAULT_SUBJECT和DEFAULT_CONTENT，因此它會(huì)自動(dòng)地使用全局的配置。同理，每個(gè)觸發(fā)器中的內(nèi)容分別對(duì)應(yīng)的 是$PROJECT_DEFAULT_SUBJECT 和 $PROJECT_DEFAULT_CONTENT，所以它也會(huì)自動(dòng)地使用項(xiàng)目的配置。由于令牌中的“值”能包含其它的令牌，這樣一來，您就能為令牌快速 地創(chuàng)建不同的切入點(diǎn)：全局級(jí)別(所有項(xiàng)目)，專屬級(jí)別(單一項(xiàng)目)，通用級(jí)別(兩者之間)。

如果你要查看所有可用的令牌，你可以點(diǎn)擊項(xiàng)目配置頁的Content Token Reference的?號(hào)獲取詳細(xì)的信息。

根據(jù)幫助文檔，我們可以了解到一些公共屬性，下面我解釋一下常用的屬性。
屬性詳解：

1、觸發(fā)器類型

注意：所有的觸發(fā)器都只能配置一次。

Failure：即時(shí)發(fā)送構(gòu)建失敗的郵件。如果”Still Failing”觸發(fā)器已配置，而上一次構(gòu)建的狀態(tài)是”Failure”，那么”Still Failing”觸發(fā)器將發(fā)送一封郵件來替代(它)。
Unstable：即時(shí)發(fā)送構(gòu)建不穩(wěn)固的郵件。如果”Still Unstable”觸發(fā)器已配置，而上一次構(gòu)建的狀態(tài)是”Unstable”，那么”Still Unstable”觸發(fā)器將發(fā)送一封郵件來替代(它)。
Still Failing：如果兩次或兩次以上連續(xù)構(gòu)建的狀態(tài)為”Failure”，發(fā)送該郵件。
Success：如果構(gòu)建的狀態(tài)為”Successful”發(fā)送郵件。如果”Fixed”已配置，而上次構(gòu)建的狀態(tài)為“Failure”或“Unstable”，那么”Fixed”觸發(fā)器將發(fā)送一封郵件來替代(它)。
Fixed：當(dāng)構(gòu)建狀態(tài)從“Failure”或“Unstable”變?yōu)?#8221;Successful”時(shí)發(fā)送郵件。
Still Unstable：如果兩次或兩次以上連續(xù)構(gòu)建的狀態(tài)為” Unstable “，發(fā)送該郵件。
Before Build：當(dāng)構(gòu)建開始時(shí)發(fā)送郵件。

2、Content Token Reference[項(xiàng)目配置]

注意：這里只解釋系統(tǒng)配置頁面中缺少的令牌。

• ${DEFAULT_SUBJECT} -這是Jenkins系統(tǒng)配置頁面默認(rèn)配置的郵件主題
• ${DEFAULT_CONTENT} -這是Jenkins系統(tǒng)配置頁面默認(rèn)配置的郵件內(nèi)容主體
• ${PROJECT_DEFAULT_SUBJECT} – 這是項(xiàng)目的默認(rèn)郵件主題。高級(jí)配置中使用該令牌的結(jié)果要優(yōu)先于Default Subject字段。警告：不要在Default Subject 或者Default Content中使用該令牌，它會(huì)產(chǎn)生一個(gè)未知的結(jié)果。
• ${PROJECT_DEFAULT_CONTENT} -這是項(xiàng)目的默認(rèn)郵件內(nèi)容主體。高級(jí)配置中使用該令牌的結(jié)果要優(yōu)先于Default Content字段。警告：不要在Default Subject 或者Default Content中使用該令牌，它會(huì)產(chǎn)生一個(gè)未知的結(jié)果。

Jelly 腳本

從Jenkins(Hudson)2.9版本開始我們可以使用Jelly腳本。Jelly腳本跟Hudson的API掛鉤，能獲得你想要的任何信息，所以它很強(qiáng)大。插件有兩個(gè)打包后的Jelly腳本，當(dāng)然你也可以自定義(腳本)。

關(guān)于插件中默認(rèn)的兩個(gè)Jelly腳本：一個(gè)用來設(shè)計(jì)HTML格式郵件，另一個(gè)則是定義TEXT格式郵件。通過上面的截圖看到它們的樣子。你能通過使用模板參數(shù)指定插件調(diào)用哪一個(gè)腳本。它們的使用方法如下：

• 文本格式： ${JELLY_SCRIPT,template=”text”}
• HTML格式: ${JELLY_SCRIPT,template=”html”}

你也能編寫屬于自己的Jelly腳本。Jelly腳本能跟Hudson的API(包括hudson.model.AbstractBuild和hudson.model.AbstractProject)掛鉤，因而特別強(qiáng)大。如果你打算這么做，你可以先參考現(xiàn)有的html和text腳本一探究竟。

值得注意的是，擁有Hudson管理員權(quán)限是使用自定義Jelly腳本(該腳本沒有跟email-ext打包)的前提。腳本的生成步驟本身其實(shí)相對(duì)簡(jiǎn)單：

1. 創(chuàng)建Jelly腳本。腳本的名稱應(yīng)該是<名稱>.jelly。名稱以.jelly結(jié)尾是很重要的。
2. 讓你的Hudson管理員把腳本存放在HUDSON_HOME\email-templates文件夾里。
3. 使用Jelly令牌，讓template匹配你的腳本名稱(不要包含后綴)。比如，腳本的名稱為foobar.jelly，則郵件內(nèi)容中應(yīng)該是${JELLY_SCRIPT,template=”foobar”}。

下面兩個(gè)圖就是就是使用Jelly腳本生成的郵件（最新版Email-ext新增html_gamil模板，它跟html模板類似，所以這里不再顯示它的截圖）：

總結(jié)

以上就是我介紹的Email-ext插件，由于自己的局限，對(duì)于它的使用沒有更深的了解。參考資料[2]中還有關(guān)于它的擴(kuò)展，你也可以自行擴(kuò)充它的功能。如果您有關(guān)于該插件以及Jenkins使用的更多更好的感受，我期待與您一起分享。

參考資料

[1] 《Maven實(shí)戰(zhàn)》第11章11.9郵件反饋。

[2] https://wiki.jenkins-ci.org/display/JENKINS/Email-ext+plugin