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

時間 2019-11-16

標籤 jenkins 進階系列使用 email ext 替換默認郵件通知欄目自動化構建简体版

原文原文鏈接

1 簡述

衆所周知，Jenkins默認提供了一個郵件通知，能在構建失敗、構建不穩定等狀態後發送郵件。可是它自己有不少侷限性，好比它的郵件通知沒法提供詳細的郵件內容、沒法定義發送郵件的格式、沒法定義靈活的郵件接收配置等等。在這樣的狀況下，咱們找到了Jenkins Email Extension Plugin。該插件能容許你自定義郵件通知的方方面面，好比在發送郵件時你能夠自定義發送給誰，發送具體什麼內容等等。本文不會告訴你如何安裝該插件，關於插件的安裝請參考這裏。html

2 配置

它主要包含兩個部分：全局配置和項目配置。java

2.1 全局配置

固然，在一個項目中應用email-ext插件以前，您必須作一些全局的配置。如今先跳轉到Jenkins的「系統設置」頁面，以下圖：正則表達式

找到標題爲「Extended E-mail Notification」的片斷，你就能配置一些全局的email-ext屬性。這些屬性必須匹配你SMTP郵件服務器的設置。這一節不只能配置成Jenkins原有郵件通知的鏡像(雖然有不少配置是同樣的，但這是個不一樣的擴展點)，並且還增長了一些額外的功能。輸入框中名爲 Default Subject 和 Default Content 的項容許你在全局級別配置郵件的內容。這樣作的話，可使您爲全部的項目按您的需求作更好的、更簡單的配置。以下圖。api

釋放個個人配置：安全

Default Subject：構建通知:$PROJECT_NAME – Build # $BUILD_NUMBER – $BUILD_STATUS!服務器

Default Content：dom

<hr/>ide

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

項目名稱：$PROJECT_NAME <hr/>post

構建編號：$BUILD_NUMBER <hr/>

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

構建狀態：$BUILD_STATUS <hr/>

觸發緣由：${CAUSE} <hr/>

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

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

變動集:${JELLY_SCRIPT,template=」html」} <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 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} -顯示測試的數量。
- 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中使用該令牌，它會產生一個未知的結果。