注：本文由Jdonee投遞
來源：http://www.juvenxu.com/2011/05/18/hudson-email-ext/
簡述
眾所周知，Jenkins(Hudson)默認提供了一個郵件通知，能在構建失敗、構建不穩定等狀態后發送郵件。但是它本身有很多局限性，比如它的郵件通知無法提供詳細的郵件內容、無法定義發送郵件的格式、無法定義靈活的郵件接收配置等等。在這樣的情況下，我們找到了Jenkins Email Extension Plugin。該插件能允許你自定義郵件通知的方方面面，比如在發送郵件時你可以自定義發送給誰，發送具體什么內容等等。本文不會告訴你如何安裝該插件，關于插件的安裝請參考這里。
功能概要
該插件擴展了Hudson構建默認的郵件通知功能，并賦予你更多更靈活的控制。它能在如下三塊區域來自定義：
- Triggers -指定發送一封郵件通知應有的前置條件。
- Content - 指定每封觸發郵件的標題和正文的內容。
- Recipients -.指定一封郵件觸發后發送給誰來接收(郵件)。
配置
它主要包含兩個部分：基本配置和項目配置。
公共配置
當然，在一個項目中應用email-ext插件之前，您必須做一些公共的配置。現在先跳轉到Hudson的“系統配置”頁面，如下圖：
找到標題為“Extended E-mail Notification”的片段，你就能配置一些公共的 email-ext屬性。這些屬性必須匹配你SMTP郵件服務器的設置。這一節不僅能配置成Hudson原有郵件通知的鏡像(雖然有很多配置是一樣的，但 這是個不同的擴展點)，而且還增加了一些額外的功能。輸入框中名為 Default Subject 和 Default Content 的項允許你在公共級別配置郵件的內容。這樣做的話，可以使您為所有的項目按您的需求做更好的、更簡單的配置。如下圖。
根據幫助文檔，我們可以了解到一些公共屬性，下面我解釋一下常用的屬性。
屬性詳解：
- Override Global Settings
如果不選，該插件將使用默認的E-mail Notification通知選項。反之，您可以通過指定不同于( 默認選項)的設置來進行覆蓋。 - Default Content Type
指定構建后發送郵件內容的類型，有Text和HTML兩種. - Use List-ID Email Header
為所有的郵件設置一個List-ID的郵件信頭，這樣你就可以在郵件客戶端使用過濾。它也能阻止郵件發件人大部分的自動回復(諸如離開辦公室、休假等 等)。你可以使用你習慣的任何名稱或者ID號，但是他們必須符合如下其中一種格式(真實的ID必須要包含在<和>標記里)：
<ci-notifications.company.org>
Build Notifications <ci-notifications.company.org>
“Build Notifications” <ci-notifications.company.org>
關于更詳細的List-ID說明請參閱RFC-2919. - Default Subject
自定義郵件通知的默認主題名稱。該插件能在郵件的主題字段中替換一些令牌，這樣你就可以從構建中包含指定的輸出信息。 - Default Content
自定義郵件通知的默認內容主體。該插件能在郵件的內容主體中替換一些令牌，這樣你就可以從構建中包含指定的輸出信息。 - Content Token Reference[公共配置]
所有的參數都是可選的，每個令牌的參數可以如下表示，字符串類型使用name=“value”，而布爾型和數字型使用name=value。如果{和}標記里面沒有參數，則不會被解析。
示例：$TOKEN, ${TOKEN}, ${TOKEN, count=100}, ${ENV, var=”PATH”}
可用令牌
- ${BUILD_LOG, maxLines, escapeHtml} -顯示最終構建日志。
- maxLines – 顯示該日志最多顯示的行數，默認250行。
- escapeHtml -如果為true，格式化HTML。默認false。
- ${BUILD_LOG_REGEX, regex, linesBefore, linesAfter, maxMatches, showTruncatedLines, substText, escapeHtml, matchedLineHtmlStyle} -按正則表達式匹配顯示構建日志的行數。
- 匹配符合該正則表達式的行數。參閱java.util.regex.Pattern，默認“(?i)\b(error|exception|fatal|fail(ed|ure)|un(defined|resolved))\b”。
- linesBefore -包含在匹配行之前的行編號。行數會與當前的另一個行匹配或者linesAfter重疊，默認0。
- linesAfter -包含在匹配行之后的行編號。行數會與當前的另一個行匹配或者linesBefore重疊，默認0。
- maxMatches -匹配的最大數量，如果為0，則包含所有匹配。默認為0。
- showTruncatedLines -如果為true，包含[...truncated ### lines...]行。默認為true。
- substText -如果非空，把這部分文字插入該郵件，而不是整行。默認為空。
- escapeHtml -如果為true，格式化HTML。默認false。
- matchedLineHtmlStyle -如果非空，輸出HTML。匹配的行數將變為<b style=”your-style-value”> html escaped matched line </b>格式。默認為空。
- ${BUILD_NUMBER} -顯示當前構建的編號。
- ${BUILD_STATUS} -顯示當前構建的狀態(失敗、成功等等)
- ${BUILD_URL} -顯示當前構建的URL地址。
- ${CHANGES, showPaths, format, pathFormat} -顯示上一次構建之后的變化。
- showPaths – 如果為 true,顯示提交修改后的地址。默認false。
- format – 遍歷提交信息，一個包含%X的字符串，其中%a表示作者，%d表示日期，%m表示消息，%p表示路徑，%r表示版本。注意，并不是所有的版本系統都支持%d和%r。如果指定showPaths將被忽略。默認“[%a] %m\n”。
- pathFormat -一個包含“%p”的字符串，用來標示怎么打印字符串。
- ${CHANGES_SINCE_LAST_SUCCESS, reverse, format, showPaths, changesFormat, pathFormat} -顯示上一次成功構建之后的變化。
- reverse -在頂部標示新近的構建。默認false。
- format -遍歷構建信息，一個包含%X的字符串，其中%c為所有的改變，%n為構建編號。默認”Changes for Build #%n\n%c\n”。
- showPaths, changesFormat, pathFormat – 分別定義如${CHANGES}的showPaths、format和pathFormat參數。
- ${CHANGES_SINCE_LAST_UNSTABLE, reverse, format, showPaths, changesFormat, pathFormat} -顯示顯示上一次不穩固或者成功的構建之后的變化。
- reverse -在頂部標示新近的構建。默認false。
- format -遍歷構建信息，一個包含%X的字符串，其中%c為所有的改變，%n為構建編號。默認”Changes for Build #%n\n%c\n”。
- showPaths, changesFormat, pathFormat -分別定義如${CHANGES}的showPaths、format和pathFormat參數。
- ${ENV, var} – 顯示一個環境變量。
- var – 顯示該環境變量的名稱。如果為空，顯示所有，默認為空。
- ${FAILED_TESTS} -如果有失敗的測試，顯示這些失敗的單元測試信息。
- ${JENKINS_URL} -顯示Jenkins服務器的地址。(你能在“系統配置”頁改變它)。
- ${HUDSON_URL} -不推薦，請使用$JENKINS_URL
- ${PROJECT_NAME} -顯示項目的名稱。
- ${PROJECT_URL} -顯示項目的URL。
- ${SVN_REVISION} -顯示SVN的版本號。
- ${CAUSE} -顯示誰、通過什么渠道觸發這次構建。
- ${JELLY_SCRIPT, template} -從一個Jelly腳本模板中自定義消息內容。有兩種模板可供配置：HTML和TEXT。你可以在$JENKINS_HOME/email-templates下自定義替換它。當使用自動義模板時，”template”參數的名稱不包含“.jelly”。
- ${FILE, path} -包含一個指定文件的內容
- path -文件路徑，注意，是工作區目錄的相對路徑。
- ${TEST_COUNTS, var} -顯示測試的數量。
- var – 默認“total”。
- total -所有測試的數量。
- fail -失敗測試的數量。
- skip -跳過測試的數量。
項目配置
要想在一個項目中使用email-ext插件，你首先必須在項目配置頁激活它。在”Post-build Actions”選項中勾選”Editable Email Notification”標簽。
項目基本配置
當插件激活后你就能編輯如下三個字段：
- Global Recipient List -這是一個以逗號(或者空格)分隔的可接受郵件的郵箱地址列表。允許您為每封郵件指定單獨的列表。
- Default Subject -允許你配置令牌，這樣就可以在項目中更容易地配置所有郵件的主題。
- Default Content -跟 Default Subject的作用一樣，但是是把主題替換內容主體。
項目高級配置
要查看插件的高級配置，請點擊”Advanced”按鈕。該選項允許您各種類型的郵件觸發器指定接收者。默認情況下，唯一使用的觸發器配置 是”Failure”觸發器。要增加更多的觸發器，選擇“Add a Trigger”旁邊下拉列表中的類型，它會增加到控件上面的列表中。一旦你增加了一個觸發器，你就可以對它做一些選擇。如果你點擊一個觸發器旁邊 的”?”號，它將告訴你你在什么前置條件中來觸發郵件發送。如下圖。
- Send to Recipient List -如果勾選，郵件將發送到”Global Recipient List”中的所有郵件地址。
- Send to Committers -該郵件會發給上次構建時檢查過代碼的人員，該插件會基于提交者的ID和追加Jenkins配置頁面的(default email suffix)默認郵件后綴來生成一個郵件地址。譬如，上次提交代碼的人是”first.last”， 默認的電子郵件后綴為“@somewhere.com”，那么電子郵件將被發送到“first.last@ somewhere.com”。
- Send To Requester -如果勾選，郵件將發送給構建觸發者。
- Include Culprits -如果勾選，而且 “Send To Committers”勾選，郵件將包含最后成功構建的提交者。
- More Configuration -通過單擊”+(expand)”鏈接您能為每個郵件觸發器作更多單獨的設置。
- Recipient List -這是一個以逗號(或者空格)分隔的可接受郵件的郵箱地址列表。如果觸發就發送郵件到該列表。該列表會追加在”Global Recipient List”里。
- Subject – 指定選擇郵件的主題。注意：高級選項中的郵件觸發器類型可覆蓋對它的配置。
- Content -指定選擇郵件的內容主體。注意：高級選項中的郵件觸發器類型可覆蓋對它的配置。
- Remove -通過單擊指定觸發器當前行的”Delete”按鈕，你可以刪除該觸發器。
項目郵件令牌
email-ext插件使用令牌來允許動態數據插入到郵件的主題和內容主體中。令牌是 一個以$(美元符號)開始，并以空格結束的字符串。當一個郵件觸發時，主題和內容主體字段的所有令牌都會通過真實的值動態地替換。同樣，令牌中的“值”能 包含其它的令牌，那將被替換成真實的內容。比如， $DEFAULT_SUBJECT令牌能通過從公共配置頁面的Default Subject字段中的文本(或者其它令牌)替換。同理， $PROJECT_DEFAULT_SUBJECT令牌也能通過項目配置頁面的Default Subject 字段中值替換。
一旦你的項目中激活email-ext插件，它會使用默認值設置郵件的內容字段。項目配置頁的默認主題和主體內容字段分別對應的是 DEFAULT_SUBJECT和DEFAULT_CONTENT，因此它會自動地使用全局的配置。同理，每個觸發器中的內容分別對應的 是$PROJECT_DEFAULT_SUBJECT 和 $PROJECT_DEFAULT_CONTENT，所以它也會自動地使用項目的配置。由于令牌中的“值”能包含其它的令牌，這樣一來，您就能為令牌快速 地創建不同的切入點：全局級別(所有項目)，專屬級別(單一項目)，通用級別(兩者之間)。
如果你要查看所有可用的令牌，你可以點擊項目配置頁的Content Token Reference的?號獲取詳細的信息。
根據幫助文檔，我們可以了解到一些公共屬性，下面我解釋一下常用的屬性。
屬性詳解：
1、觸發器類型
注意：所有的觸發器都只能配置一次。
Failure：即時發送構建失敗的郵件。如果”Still Failing”觸發器已配置，而上一次構建的狀態是”Failure”，那么”Still Failing”觸發器將發送一封郵件來替代(它)。
Unstable：即時發送構建不穩固的郵件。如果”Still Unstable”觸發器已配置，而上一次構建的狀態是”Unstable”，那么”Still Unstable”觸發器將發送一封郵件來替代(它)。
Still Failing：如果兩次或兩次以上連續構建的狀態為”Failure”，發送該郵件。
Success：如果構建的狀態為”Successful”發送郵件。如果”Fixed”已配置，而上次構建的狀態為“Failure”或“Unstable”，那么”Fixed”觸發器將發送一封郵件來替代(它)。
Fixed：當構建狀態從“Failure”或“Unstable”變為”Successful”時發送郵件。
Still Unstable：如果兩次或兩次以上連續構建的狀態為” Unstable “，發送該郵件。
Before Build：當構建開始時發送郵件。
2、Content Token Reference[項目配置]
注意：這里只解釋系統配置頁面中缺少的令牌。
- ${DEFAULT_SUBJECT} -這是Jenkins系統配置頁面默認配置的郵件主題
- ${DEFAULT_CONTENT} -這是Jenkins系統配置頁面默認配置的郵件內容主體
- ${PROJECT_DEFAULT_SUBJECT} – 這是項目的默認郵件主題。高級配置中使用該令牌的結果要優先于Default Subject字段。警告：不要在Default Subject 或者Default Content中使用該令牌，它會產生一個未知的結果。
- ${PROJECT_DEFAULT_CONTENT} -這是項目的默認郵件內容主體。高級配置中使用該令牌的結果要優先于Default Content字段。警告：不要在Default Subject 或者Default Content中使用該令牌，它會產生一個未知的結果。
Jelly 腳本
從Jenkins(Hudson)2.9版本開始我們可以使用Jelly腳本。Jelly腳本跟Hudson的API掛鉤，能獲得你想要的任何信息，所以它很強大。插件有兩個打包后的Jelly腳本，當然你也可以自定義(腳本)。
關于插件中默認的兩個Jelly腳本：一個用來設計HTML格式郵件，另一個則是定義TEXT格式郵件。通過上面的截圖看到它們的樣子。你能通過使用模板參數指定插件調用哪一個腳本。它們的使用方法如下：
- 文本格式： ${JELLY_SCRIPT,template=”text”}
- HTML格式: ${JELLY_SCRIPT,template=”html”}
你也能編寫屬于自己的Jelly腳本。Jelly腳本能跟Hudson的API(包括hudson.model.AbstractBuild和hudson.model.AbstractProject)掛鉤，因而特別強大。如果你打算這么做，你可以先參考現有的html和text腳本一探究竟。
值得注意的是，擁有Hudson管理員權限是使用自定義Jelly腳本(該腳本沒有跟email-ext打包)的前提。腳本的生成步驟本身其實相對簡單：
- 創建Jelly腳本。腳本的名稱應該是<名稱>.jelly。名稱以.jelly結尾是很重要的。
- 讓你的Hudson管理員把腳本存放在HUDSON_HOME\email-templates文件夾里。
- 使用Jelly令牌，讓template匹配你的腳本名稱(不要包含后綴)。比如，腳本的名稱為foobar.jelly，則郵件內容中應該是${JELLY_SCRIPT,template=”foobar”}。
下面兩個圖就是就是使用Jelly腳本生成的郵件（最新版Email-ext新增html_gamil模板，它跟html模板類似，所以這里不再顯示它的截圖）：
總結
以上就是我介紹的Email-ext插件，由于自己的局限，對于它的使用沒有更深的了解。參考資料[2]中還有關于它的擴展，你也可以自行擴充它的功能。如果您有關于該插件以及Jenkins使用的更多更好的感受，我期待與您一起分享。
參考資料
[1] 《Maven實戰》第11章11.9郵件反饋。
[2] https://wiki.jenkins-ci.org/display/JENKINS/Email-ext+plugin