注：本文由Jdonee投遞
來源：http://www.juvenxu.com/2011/05/18/hudson-email-ext/
簡述
眾所周知，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)容等等。本文不會告訴你如何安裝該插件，關(guān)于插件的安裝請參考這里。
功能概要
該插件擴(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插件之前，您必須做一些公共的配置。現(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)允許你在公共級別配置郵件的內(nèi)容。這樣做的話，可以使您為所有的項(xiàng)目按您的需求做更好的、更簡單的配置。如下圖。
根據(jù)幫助文檔，我們可以了解到一些公共屬性，下面我解釋一下常用的屬性。
屬性詳解：
- Override Global Settings
如果不選，該插件將使用默認(rèn)的E-mail Notification通知選項(xiàng)。反之，您可以通過指定不同于( 默認(rèn)選項(xiàng))的設(shè)置來進(jìn)行覆蓋。 - Default Content Type
指定構(gòu)建后發(fā)送郵件內(nèi)容的類型，有Text和HTML兩種. - Use List-ID Email Header
為所有的郵件設(shè)置一個(gè)List-ID的郵件信頭，這樣你就可以在郵件客戶端使用過濾。它也能阻止郵件發(fā)件人大部分的自動回復(fù)(諸如離開辦公室、休假等 等)。你可以使用你習(xí)慣的任何名稱或者ID號，但是他們必須符合如下其中一種格式(真實(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說明請參閱RFC-2919. - Default Subject
自定義郵件通知的默認(rèn)主題名稱。該插件能在郵件的主題字段中替換一些令牌，這樣你就可以從構(gòu)建中包含指定的輸出信息。 - Default Content
自定義郵件通知的默認(rèn)內(nèi)容主體。該插件能在郵件的內(nèi)容主體中替換一些令牌，這樣你就可以從構(gòu)建中包含指定的輸出信息。 - Content Token Reference[公共配置]
所有的參數(shù)都是可選的，每個(gè)令牌的參數(shù)可以如下表示，字符串類型使用name=“value”，而布爾型和數(shù)字型使用name=value。如果{和}標(biāo)記里面沒有參數(shù)，則不會被解析。
示例：$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 -包含在匹配行之前的行編號。行數(shù)會與當(dāng)前的另一個(gè)行匹配或者linesAfter重疊，默認(rèn)0。
- linesAfter -包含在匹配行之后的行編號。行數(shù)會與當(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)建的編號。
- ${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)建編號。默認(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)建編號。默認(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} -如果有失敗的測試，顯示這些失敗的單元測試信息。
- ${JENKINS_URL} -顯示Jenkins服務(wù)器的地址。(你能在“系統(tǒng)配置”頁改變它)。
- ${HUDSON_URL} -不推薦，請使用$JENKINS_URL
- ${PROJECT_NAME} -顯示項(xiàng)目的名稱。
- ${PROJECT_URL} -顯示項(xiàng)目的URL。
- ${SVN_REVISION} -顯示SVN的版本號。
- ${CAUSE} -顯示誰、通過什么渠道觸發(fā)這次構(gòu)建。
- ${JELLY_SCRIPT, template} -從一個(gè)Jelly腳本模板中自定義消息內(nèi)容。有兩種模板可供配置：HTML和TEXT。你可以在$JENKINS_HOME/email-templates下自定義替換它。當(dāng)使用自動義模板時(shí)，”template”參數(shù)的名稱不包含“.jelly”。
- template -模板名稱，默認(rèn)”html”。
- ${FILE, path} -包含一個(gè)指定文件的內(nèi)容
- path -文件路徑，注意，是工作區(qū)目錄的相對路徑。
- ${TEST_COUNTS, var} -顯示測試的數(shù)量。
- var – 默認(rèn)“total”。
- total -所有測試的數(shù)量。
- fail -失敗測試的數(shù)量。
- skip -跳過測試的數(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è)以逗號(或者空格)分隔的可接受郵件的郵箱地址列表。允許您為每封郵件指定單獨(dú)的列表。
- Default Subject -允許你配置令牌，這樣就可以在項(xiàng)目中更容易地配置所有郵件的主題。
- Default Content -跟 Default Subject的作用一樣，但是是把主題替換內(nèi)容主體。
項(xiàng)目高級配置
要查看插件的高級配置，請點(diǎn)擊”Advanced”按鈕。該選項(xiàng)允許您各種類型的郵件觸發(fā)器指定接收者。默認(rèn)情況下，唯一使用的觸發(fā)器配置 是”Failure”觸發(fā)器。要增加更多的觸發(fā)器，選擇“Add a Trigger”旁邊下拉列表中的類型，它會增加到控件上面的列表中。一旦你增加了一個(gè)觸發(fā)器，你就可以對它做一些選擇。如果你點(diǎn)擊一個(gè)觸發(fā)器旁邊 的”?”號，它將告訴你你在什么前置條件中來觸發(fā)郵件發(fā)送。如下圖。
- Send to Recipient List -如果勾選，郵件將發(fā)送到”Global Recipient List”中的所有郵件地址。
- Send to Committers -該郵件會發(fā)給上次構(gòu)建時(shí)檢查過代碼的人員，該插件會基于提交者的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è)以逗號(或者空格)分隔的可接受郵件的郵箱地址列表。如果觸發(fā)就發(fā)送郵件到該列表。該列表會追加在”Global Recipient List”里。
- Subject – 指定選擇郵件的主題。注意：高級選項(xiàng)中的郵件觸發(fā)器類型可覆蓋對它的配置。
- Content -指定選擇郵件的內(nèi)容主體。注意：高級選項(xiàng)中的郵件觸發(fā)器類型可覆蓋對它的配置。
- Remove -通過單擊指定觸發(fā)器當(dāng)前行的”Delete”按鈕，你可以刪除該觸發(fā)器。
項(xiàng)目郵件令牌
email-ext插件使用令牌來允許動態(tài)數(shù)據(jù)插入到郵件的主題和內(nèi)容主體中。令牌是 一個(gè)以$(美元符號)開始，并以空格結(jié)束的字符串。當(dāng)一個(gè)郵件觸發(fā)時(shí)，主題和內(nèi)容主體字段的所有令牌都會通過真實(shí)的值動態(tài)地替換。同樣，令牌中的“值”能 包含其它的令牌，那將被替換成真實(shí)的內(nèi)容。比如， $DEFAULT_SUBJECT令牌能通過從公共配置頁面的Default Subject字段中的文本(或者其它令牌)替換。同理， $PROJECT_DEFAULT_SUBJECT令牌也能通過項(xiàng)目配置頁面的Default Subject 字段中值替換。
一旦你的項(xiàng)目中激活email-ext插件，它會使用默認(rèn)值設(shè)置郵件的內(nèi)容字段。項(xiàng)目配置頁的默認(rèn)主題和主體內(nèi)容字段分別對應(yīng)的是 DEFAULT_SUBJECT和DEFAULT_CONTENT，因此它會自動地使用全局的配置。同理，每個(gè)觸發(fā)器中的內(nèi)容分別對應(yīng)的 是$PROJECT_DEFAULT_SUBJECT 和 $PROJECT_DEFAULT_CONTENT，所以它也會自動地使用項(xiàng)目的配置。由于令牌中的“值”能包含其它的令牌，這樣一來，您就能為令牌快速 地創(chuàng)建不同的切入點(diǎn)：全局級別(所有項(xiàng)目)，專屬級別(單一項(xiàng)目)，通用級別(兩者之間)。
如果你要查看所有可用的令牌，你可以點(diǎn)擊項(xiàng)目配置頁的Content Token Reference的?號獲取詳細(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)郵件主題。高級配置中使用該令牌的結(jié)果要優(yōu)先于Default Subject字段。警告：不要在Default Subject 或者Default Content中使用該令牌，它會產(chǎn)生一個(gè)未知的結(jié)果。
- ${PROJECT_DEFAULT_CONTENT} -這是項(xiàng)目的默認(rèn)郵件內(nèi)容主體。高級配置中使用該令牌的結(jié)果要優(yōu)先于Default Content字段。警告：不要在Default Subject 或者Default Content中使用該令牌，它會產(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í)相對簡單：
- 創(chuàng)建Jelly腳本。腳本的名稱應(yīng)該是<名稱>.jelly。名稱以.jelly結(jié)尾是很重要的。
- 讓你的Hudson管理員把腳本存放在HUDSON_HOME\email-templates文件夾里。
- 使用Jelly令牌，讓template匹配你的腳本名稱(不要包含后綴)。比如，腳本的名稱為foobar.jelly，則郵件內(nèi)容中應(yīng)該是${JELLY_SCRIPT,template=”foobar”}。
下面兩個(gè)圖就是就是使用Jelly腳本生成的郵件（最新版Email-ext新增html_gamil模板，它跟html模板類似，所以這里不再顯示它的截圖）：
總結(jié)
以上就是我介紹的Email-ext插件，由于自己的局限，對于它的使用沒有更深的了解。參考資料[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