hudson 郵件的設定

使用email-ext替換Jenkins(Hudson)的預設郵件通知

May 18th, 2011 Leave a comment Go to comments

注：本文由Jdonee投遞

簡述

衆所周知，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 的項允許你在公共級别配置郵件的内容。這樣做的話，可以使您為所有的項目按您的需求做更好的、更簡單的配置。如下圖。

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

屬性詳解：

1. Override Global Settings

   如果不選，該插件将使用預設的E-mail Notification通知選項。反之，您可以通過指定不同于( 預設選項)的設定來進行覆寫。

2. Default Content Type

   指定建構後發送郵件内容的類型，有Text和HTML兩種.

3. 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.

4. Default Subject

   自定義郵件通知的預設主題名稱。該插件能在郵件的主題字段中替換一些令牌，這樣你就可以從建構中包含指定的輸出資訊。

5. Default Content

   自定義郵件通知的預設内容主體。該插件能在郵件的内容主體中替換一些令牌，這樣你就可以從建構中包含指定的輸出資訊。

6. 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”。
  • template -模闆名稱，預設”html”。
• ${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”，那麼電子郵件将被發送到“[email protected] 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打包)的前提。腳本的生成步驟本身其實相對簡單：

1. 建立Jelly腳本。腳本的名稱應該是<名稱>.jelly。名稱以.jelly結尾是很重要的。
2. 讓你的Hudson管理者把腳本存放在HUDSON_HOME\email-templates檔案夾裡。
3. 使用Jelly令牌，讓template比對你的腳本名稱(不要包含字尾)。比如，腳本的名稱為foobar.jelly，則郵件内容中應該是${JELLY_SCRIPT,template=”foobar”}。

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

總結

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