1  簡述

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

2  配置

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

2.1 全域性配置

當然，在一個專案中應用  email-ext  外掛之前，您必須做一些全域性的配置。現在先跳轉到  Jenkins  的 “ 系統設定 ” 頁面，如下圖： 找到標題為 “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:someone@somewhere.com

6. Reply To List ：回覆列表 , A comma separated list of e-mail addresses to use in the ReplyTo 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} 按正規表示式匹配並顯示構建日誌。

regex  java.util.regex.Pattern   生成正規表示式匹配的構建日誌。無預設值，可為空。

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 #%nn%cn” 。

showPaths,changesFormat,pathFormat  分別定義如 ${CHANGES} 的  showPaths 、 format  和 pathFormat  引數。

${CHANGES_SINCE_LAST_UNSTABLE} - 顯示顯示上一次不穩固或者成功的構建之後的變化。

reverse  在頂部標示新近的構建。預設  false 。

format  遍歷構建資訊，一個包含 %X  的字串，其中 %c  為所有的改變， %n  為構建編號。預設 ”Changes  for Build #%nn%cn” 。

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” ，那麼電子郵件將被髮送到 “first.last@ 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_HOMEemail-templates  資料夾裡。

3.  使用  Jelly  變數，讓  template  匹配你的指令碼名稱 ( 不要包含字尾 ) 。比如，指令碼的名稱為  foobar.jelly ，則郵件內容 中應該是 ${JELLY_SCRIPT,template=”foobar”} 。 下面兩個圖就是就是使用  Jelly  指令碼生成的郵件（最新版  Email-ext  新增  html_gamil  模板，它跟  html  模板類似，所以這裡 不再顯示它的截圖）：

4  總結

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