1 簡述

眾所周知，Jenkins預設提供了一個郵件通知，能在構建失敗、構建不穩定等狀態後傳送郵件。但是它本身有很多侷限性，比如它的郵件通知無法提供詳細的郵件內容、無法定義傳送郵件的格式、無法定義靈活的郵件接收配置等等。在這樣的情況下，我們找到了Jenkins Email Extension Plugin。該外掛能允許你自定義郵件通知的方方面面，比如在傳送郵件時你可以自定義傳送給誰，傳送具體什麼內容等等。本文不會告訴你如何安裝該外掛，關於外掛的安裝請參考這裡。

2 配置

它主要包含兩個部分：全域性配置和專案配置。

2.1 全域性配置

當然，在一個專案中應用email-ext外掛之前，您必須做一些

找到標題為“Extended E-mail Notification”的片段，你就能配置一些全域性的email-ext屬性。這些屬性必須匹配你SMTP郵件伺服器的設定。這一節不僅能配置成Jenkins原有郵件通知的映象(雖然有很多配置是一樣的，但這是個不同的擴充套件點)，而且還增加了一些額外的功能。輸入框中名為 Default Subject 和 Default Content 的項允許你在全域性級別配置郵件的內容。這樣做的話，可以使您為所有的專案按您的需求做更好的、更簡單的配置。如下圖。

釋放個我的配置：

Default Subject：構建通知:$PROJECT_NAME - Build # $BUILD_NUMBER - $BUILD_STATUS!

Default Content：

<hr/>

(本郵件是程式自動下發的，請勿回覆！)<br/><hr/>

專案名稱：$PROJECT_NAME<br/><hr/>

構建編號：$BUILD_NUMBER<br/><hr/>

svn版本號：${SVN_REVISION}<br/><hr/>

構建狀態：$BUILD_STATUS<br/><hr/>

觸發原因：${CAUSE}<br/><hr/>

構建日誌地址：<a href="${BUILD_URL}console">${BUILD_URL}console</a><br/><hr/>

構建地址：<a href="$BUILD_URL">$BUILD_URL</a><br/><hr/>

變更集:${JELLY_SCRIPT,template="html"}<br/><hr/>

下面解釋一下常用的屬性。

2.1.1 全域性屬性詳解

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. Add 'Precedence: bulk' Email Header：設定優先順序,更詳細說明請參閱RFC-3834.

5. Default Recipients：自定義預設電子郵件收件人列表。如果沒有被專案配置覆蓋,該外掛會使用這個列表。您可以在專案配置使用$ DEFAULT_RECIPIENTS引數包括此預設列表，以及新增新的地址在專案級別。新增抄送：cc:電子郵件地址例如,CC:[email protected]

6. Reply To List：回覆列表, A comma separated list of e-mail addresses to use in the Reply-To header of the email. This value will be available as $DEFAULT_REPLYTO in the project configuration.

7. Emergency reroute：如果這個欄位不為空，所有的電子郵件將被單獨傳送到該地址（或地址列表）。

8. Excluded Committers：防止郵件被郵件系統認為是垃圾郵件,郵件列表應該沒有擴充套件的賬戶名(如:@domain.com),並且使用逗號分隔

9. Default Subject：自定義郵件通知的預設主題名稱。該選項能在郵件的主題欄位中替換一些引數，這樣你就可以在構建中包含指定的輸出資訊。

10. Maximum Attachment Size：郵件最大附件大小。

11. Default Content：自定義郵件通知的預設內容主體。該選項能在郵件的內容中替換一些引數，這樣你就可以在構建中包含指定的輸出資訊。

12. Default Pre-send Script：預設傳送前執行的指令碼（注：grooy指令碼，這是我在某篇文章上看到的，不一定準確）。

13. Enable Debug Mode：啟用外掛的除錯模式。這將增加額外的日誌輸出，構建日誌以及Jenkins的日誌。在除錯時是有用的，但不能用於生產。

14. Enable Security：啟用時，會禁用傳送指令碼的能力，直接進入Jenkins例項。如果使用者試圖訪問Jenkins管理物件例項，將丟擲一個安全異常。

15. Content Token Reference：郵件中可以使用的變數，所有的變數都是可選的。具體介紹請檢視全域性郵件變數章節。

2.1.2 全域性郵件變數

Ps：看著感覺有點暈頭，對比著Jenkins頁面看要好些。

email-ext外掛允許使用變數來動態插入資料到郵件的主題和內容主體中。變數是一個以$(美元符號)開始，並以空格結束的字串。當一個郵件觸發時，主題和內容主體欄位的所有變數都會通過真實的值動態地替換。同樣，變數中的“值”能包含其它的變數，都將被替換成真實的內容。

比如，專案配置頁的預設主題和內容分別對應的是全域性配置頁面的DEFAULT_SUBJECT和DEFAULT_CONTENT，因此它會自動地使用全域性的配置。同理，觸發器中的Subject和Content分別對應的是專案配置頁面的DEFAULT_SUBJECT和DEFAULT_CONTENT，所以它也會自動地使用專案的配置。由於變數中的“值”能包含其它的變數，所以就能為變數快速地建立不同的切入點：全域性級別(所有專案)，專屬級別(單一專案)，觸發器級別(構建結果)。

如果你要檢視所有可用的變數，你可以點選配置頁的Content Token Reference的問號獲取詳細的資訊。

所有的變數都是可選的，每個變數可以如下表示，字串型別使用name=“value”，而布林型和數字型使用name=value。如果{和}標記裡面沒有變數，則不會被解析。示例：$TOKEN,${TOKEN},${TOKEN,count=100},${ENV,var=”PATH”}

提示：用英文逗號分隔變數的引數。

下面我解釋一下常用的屬性。

•  ${FILE,path="PATH"} 包括指定檔案（路徑）的含量相對於工作空間根目錄。
  • path檔案路徑，注意：是工作區目錄的相對路徑。
•  ${BUILD_NUMBER} 顯示當前構建的編號。
•  ${JOB_DESCRIPTION} 顯示專案描述。
•  ${SVN_REVISION} 顯示svn版本號。還支援Subversion外掛出口的SVN_REVISION_n版本。
•  ${CAUSE} 顯示誰、通過什麼渠道觸發這次構建。
•  ${CHANGES } -顯示上一次構建之後的變化。
  • showPaths 如果為 true,顯示提交修改後的地址。預設false。
  • showDependencies 如果為true，顯示專案構建依賴。預設為false
  • format 遍歷提交資訊，一個包含%X的字串，其中%a表示作者，%d表示日期，%m表示訊息，%p表示路徑，%r表示版本。注意，並不是所有的版本系統都支援%d和%r。如果指定showPaths將被忽略。預設“[%a] %m\\n”。
  • pathFormat 一個包含“%p”的字串，用來標示怎麼列印路徑。
•  ${BUILD_ID}顯示當前構建生成的ID。
•  ${PROJECT_NAME} 顯示專案的全名。（見AbstractProject.getFullDisplayName）
•  ${PROJECT_DISPLAY_NAME} 顯示專案的顯示名稱。（見AbstractProject.getDisplayName）
•  ${SCRIPT} 從一個指令碼生成自定義訊息內容。自定義指令碼應該放在"$JENKINS_HOME/email-templates"。當使用自定義指令碼時會預設搜尋$JENKINS_HOME/email-templatesdirectory目錄。其他的目錄將不會被搜尋。
  •  script 當其使用的時候，僅僅只有最後一個值會被指令碼使用（不能同時使用script和template）。
  •  template常規的simpletemplateengine格式模板。
•  ${JENKINS_URL} 顯示Jenkins伺服器的url地址（你可以再系統配置頁更改）。
•  ${BUILD_LOG_MULTILINE_REGEX}按正則表示式匹配並顯示構建日誌。
  •  maxMatches 匹配的最大數量。如果為0，將匹配所有。預設為0。
  •  showTruncatedLines 如果為true，包含[...truncated ### lines...]行。預設為true。
  •  substText 如果非空，就把這部分文字（而不是整行）插入該郵件。預設為空。
  • escapeHtml 如果為true，格式化HTML。預設為false。
  •  matchedSegmentHtmlStyle 如果非空，輸出HTML。匹配的行數將變為<b style=”your-style-value”> html escaped matched line </b>格式。預設為空。
•  ${BUILD_LOG} 顯示最終構建日誌。
  •  maxLines 日誌最多顯示的行數，預設250行。
  •  escapeHtml 如果為true，格式化HTML。預設false。
•  ${PROJECT_URL} 顯示專案的URL地址。
•  ${BUILD_STATUS} -顯示當前構建的狀態(失敗、成功等等)
•  ${BUILD_URL} -顯示當前構建的URL地址。
•  ${CHANGES_SINCE_LAST_SUCCESS} -顯示上一次成功構建之後的變化。
  •  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在頂部標示新近的構建。預設false。
  •  format遍歷構建資訊，一個包含%X的字串，其中%c為所有的改變，%n為構建編號。預設”Changes for Build #%n\n%c\n”。
  •  showPaths,changesFormat,pathFormat分別定義如${CHANGES}的showPaths、format和pathFormat引數。
•  ${ENV} –顯示一個環境變數。
  •  var– 顯示該環境變數的名稱。如果為空，顯示所有，預設為空。
•  ${FAILED_TESTS} -如果有失敗的測試，顯示這些失敗的單元測試資訊。
•  ${JENKINS_URL} -顯示Jenkins伺服器的地址。(你能在“系統配置”頁改變它)。
•  ${HUDSON_URL} -不推薦，請使用$JENKINS_URL
•  ${PROJECT_URL} -顯示專案的URL。
•  ${SVN_REVISION} -顯示SVN的版本號。
•  ${JELLY_SCRIPT} -從一個Jelly指令碼模板中自定義訊息內容。有兩種模板可供配置：HTML和TEXT。你可以在$JENKINS_HOME/email-templates下自定義替換它。當使用自動義模板時，”template”引數的名稱不包含“.jelly”。
  •  template模板名稱，預設”html”。
•  ${TEST_COUNTS} -顯示測試的數量。
  • var– 預設“total”。
    • total -所有測試的數量。
    •  fail -失敗測試的數量。
    •  skip -跳過測試的數量。

2.2 專案配置

要想在一個專案中使用email-ext外掛，你首先必須在專案配置頁啟用它。在構建後操作——”Add Post-build Actions”選項中勾選”Editable Email Notification”標籤。

2.2.1 專案基本配置

當外掛啟用後你就能編輯如下欄位（只列出常用的欄位）：

•  Project Recipient List：這是一個以逗號(或者空格)分隔的收件人郵件的郵箱地址列表。允許您為每封郵件指定單獨的列表。Ps：如果你想在預設收件人的基礎上新增收件人：$DEFAULT_RECIPIENTS,<新的收件人>
•  Default Subject：允許你配置此專案郵件的主題。
•  Default Content：跟Default Subject的作用一樣，但是是替換郵件內容。
•  Attach Build Log：附件構建日誌。
  •  Compress Build Log before sending：傳送前壓縮生成日誌（zip格式）。

2.2.1.1 專案高階配置

要檢視外掛的高階配置，請點選”高階”按鈕。該選項允許您各種型別的郵件觸發器指定接收者。預設情況下，是沒有配置的觸發器，所以預設情況下不會發送郵件。要增加更多的觸發器，選擇“Add a Trigger”旁邊下拉列表中的型別，它會增加到控制元件上面的列表中。一旦你增加了一個觸發器，你就可以對它做一些選擇。如果你點選一個觸發器旁邊的”?”號，它將告訴你在什麼條件下會觸發郵件傳送。如下圖。

•  Send to Recipient List：如果勾選，郵件將傳送到”Project 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”按鈕，你可以刪除該觸發器。

2.2.1.2 觸發器型別

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

• 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.2.1.3 專案郵件變數

注意：這裡只解釋全域性配置頁面中缺少的變數。

• ${DEFAULT_SUBJECT}：這是Jenkins系統配置頁面預設配置的郵件主題
• ${DEFAULT_CONTENT}：這是Jenkins系統配置頁面預設配置的郵件內容主體
• ${PROJECT_DEFAULT_SUBJECT}：這是專案的預設郵件主題。高階配置中使用該令牌的結果要優先於Default Subject欄位。警告：不要在Default Subject 或者Default Content中使用該令牌，它會產生一個未知的結果。
• ${PROJECT_DEFAULT_CONTENT}：這是專案的預設郵件內容主體。高階配置中使用該令牌的結果要優先於Default Content欄位。警告：不要在Default Subject 或者Default Content中使用該令牌，它會產生一個未知的結果。

3 Jelly指令碼

從Jenkins 2.9版本開始我們可以使用Jelly指令碼。Jelly指令碼跟Hudson的API掛鉤，能獲得你想要的任何資訊，所以它很強大。外掛有兩個打包後的Jelly指令碼，當然你也可以自定義(指令碼)。

關於外掛中預設的兩個Jelly指令碼：一個用來設計HTML格式郵件，另一個則是定義TEXT格式郵件。你能通過使用模板引數指定外掛呼叫哪一個指令碼。它們的使用方法如下：

 文字格式：${JELLY_SCRIPT,template=”text”}

 HTML格式:${JELLY_SCRIPT,template=”html”}

你也能編寫屬於自己的Jelly指令碼。Jelly指令碼能跟Jenkins 的API(包括hudson.model.AbstractBuild和hudson.model.AbstractProject)掛鉤，因而特別強大。如果你打算這麼做，你可以先參考現有的html和text指令碼一探究竟。

值得注意的是，擁有Hudson管理員許可權是使用自定義Jelly指令碼(該指令碼沒有跟email-ext打包)的前提。指令碼的生成步驟本身其實相對簡單：

1. 建立Jelly指令碼。指令碼的名稱應該是<名稱>.jelly。名稱以.jelly結尾是很重要的。

2. 把指令碼存放在JENKINS_HOME\email-templates資料夾裡。

3. 使用Jelly變數，讓template匹配你的指令碼名稱(不要包含字尾)。比如，指令碼的名稱為foobar.jelly，則郵件內容中應該是${JELLY_SCRIPT,template=”foobar”}。

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

4 總結

以上就是我介紹的Email-ext外掛，由於自己的侷限，對於它的使用沒有更深的瞭解。參考資料[2]中還有關於它的擴充套件，你也可以自行擴充它的功能。文章部分內容來源於參考資料[3]。如果您有關於該外掛以及Jenkins使用的更多更好的感受，我期待與您一起分享。

5 參考資料

[1]《Maven實戰》第11章11.9郵件反饋。

PDF文件下載：點我下載