Jenkins進階系列之——01使用email-ext替換Jenkins的預設郵件通知

Hudson · 發表 2018-11-12 16:28:11

摘要： 1 簡述眾所周知，Jenkins預設提供了一個郵件通知，能在構建失敗、構建不穩定等狀態後傳送郵件。但是它本身有很多侷限性，比如它的郵件通知無法提供詳細的郵件內容、無法定義傳送郵件的格式、無法定義靈活的郵件接收配置等等。在這樣的情況下，我們找到了Jenkins Email Extension ...

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：

(本郵件是程式自動下發的，請勿回覆！)

專案名稱：$PROJECT_NAME

構建編號：$BUILD_NUMBER

svn版本號：${SVN_REVISION}

構建狀態：$BUILD_STATUS

觸發原因：${CAUSE}

構建日誌地址：${BUILD_URL}console

構建地址：$BUILD_URL

變更集:${JELLY_SCRIPT,template=”html”}

下面解釋一下常用的屬性。 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必須要包含在<和> 標記裡)： Build Notifications “Build Notifications” 關於更詳細的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}按正則表示式匹配並顯示構建日誌。 ● regex java.util.regex.Pattern 生成正則表示式匹配的構建日誌。無預設值，可為空。 ● maxMatches 匹配的最大數量。如果為0，將匹配所有。預設為0。 ● showTruncatedLines 如果為true，包含[…truncated ### lines…]行。預設為true。 ● substText 如果非空，就把這部分文字（而不是整行）插入該郵件。預設為空。 ● escapeHtml 如果為true，格式化HTML。預設為false。 ● matchedSegmentHtmlStyle 如果非空，輸出HTML。匹配的行數將變為html escaped matched line

格式。預設為空。 ● ${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} -顯示測試的數量。 ● total -所有測試的數量。 ● fail -失敗測試的數量。 ● skip -跳過測試的數量。 ● var– 預設“total”。 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打包)的前提。指令碼的生成步驟本身其實相對簡單：

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

4 總結以上就是我介紹的Email-ext外掛，由於自己的侷限，對於它的使用沒有更深的瞭解。參考資料[2]中還有關於它的擴充套件，你也可以自行擴充它的功能。文章部分內容來源於參考資料[3]。如果您有關於該外掛以及Jenkins使用的更多更好的感受，我期待與您一起分享。原文釋出時間為：2018-11-11 本文來自雲棲社群合作伙伴“Java雜記”，瞭解相關資訊可以關注“Java雜記”。

Jenkins進階系列之——01使用email-ext替換Jenkins的預設郵件通知

您可能也會喜歡…