Jenkins : 郵件通知

sparkdev發表於2017-08-21
Jenkins

目錄

Jenkins 內建了 Mailer 外掛用於傳送郵件通知，但是 Mailer 外掛的功能比較簡單，無法按照使用者的需求進行郵件的定製。Email Extension 是 Jenkins 預設推薦安裝的一款功能強大的郵件外掛，使用它幾乎可以定製郵件的任何部分。本文將結合筆者的使用經驗介紹 Email Extension 外掛的使用方法。

全域性配置

和其它的外掛一樣，Email Extension 外掛的全域性配置也是在 Jenkins -> Manage Jenkins -> Configure System 中。具體的配置項非常多，下面介紹幾個比較基本且重要的配置項。

SMTP server
設定 smtp server 的名稱或 IP 地址。

郵件型別
可以選擇 HTML 格式的郵件或者是純文字格式的郵件：

預設標題
預設的標題為：

$PROJECT_NAME - Build # $BUILD_NUMBER - $BUILD_STATUS!

顯示專案名稱，Build 號和 Build 結果。如果沒有其它的要求，這個標題也算是簡單明瞭啊！

預設的郵件內容
預設的郵件內容為：

$PROJECT_NAME - Build # $BUILD_NUMBER - $BUILD_STATUS:

Check console output at $BUILD_URL to view the results.

一般我們會透過郵件模板等功能實現一個完整的郵件內容，所以可以忽略這個預設的內容。

預設的觸發條件
作為一種通知方式，在什麼條件下觸發郵件通知是極為重要的。Email Extension 外掛支援的觸發器型別是很豐富的：

個人覺得這裡的預設設定沒那麼重要，因為每個專案的情況都是不一樣的，所以最終都需要在專案上進行設定。而專案上的設定會覆蓋這裡的預設設定。

為專案新增郵件通知

在專案的配置項中新增 Post-build Actions，選擇 "Editable Email Notification"：

然後就可以進行詳細的設定了：

下面介紹一下比較重要的配置項。

關閉郵件通知

這個選項在維護專案時非常有用，可以臨時關閉郵件通知，避免把不必要的郵件傳送給使用者。

收件人列表
收件人郵件地址，多於一個時需要使用逗號分隔。

郵件型別
和全域性設定中的郵件型別一樣，沒有特殊要求的話保留預設型別即可。此時會應用全域性設定中的型別。

預設標題
標題的預設內容為：$DEFAULT_SUBJECT，也就是在全域性配置中設定的內容。如果覺著不爽可以進行深度定製，也就是使用系統提供的變數進行拼湊。至於能拿到什麼變數，可以參考 Conten Token Reference 的內容：

點選問號圖示就會列出所有可用的變數，實在是太多了，就不貼出來佔篇幅了！

預設內容
預設內容為：$DEFAULT_CONTENT，也是在全域性配置中設定的內容。和預設標題一樣，你也可以自行定義。但多數情況下都會使用後面介紹的郵件模板，這裡就不囉嗦了。

附件
有時把一些 Build 產物作為通知郵件的附件是很有用的。這裡我們也可以輕鬆實現：

我們可以指定檔案的名稱，也可以使用萬用字元。
除了 Build 的產物，Build 的日誌也是極其重要的資訊。它可以幫助我們快速的調查 Build 過程中的各種問題，所以也應該把 Build 日誌新增為郵件的附件：

測試一下，收到的郵件帶了兩個附件：

郵件模板

郵件的內容可以包含大量的資訊，如果每個專案中都自己組織這些資訊會費時費力。使用郵件的模板功能可以極大的提高生產力！
Email Extension 外掛支援兩種型別的郵件模板，分別是 Jelly 模板和 Groovy 模板。當前的現狀是 Groovy 模板正在逐步的取代 Jelly 模板。但是兩種模板的設定和使用方式基本一樣，我們以 Groovy 模板為例進行介紹。
在 Email Extension 外掛的官方文件中可以找到模板的下載地址。筆者以下載的 groovy-html.template 檔案為例進行說明。首先是安裝郵件模板，其實就是把模板檔案複製到 Jenkins 安裝目錄下的 email-templates 目錄中，如果該目錄不存在就先建立它。
接著我們可以測試一下安裝的模板是否能正常工作。開啟一個新增了 "Editable Email Notification" 的專案，你會發現在左邊的選單中多了一項 "Email Template Testing"：

選擇這個選單項並且輸入剛才安裝的模板名稱：

點選 "Go" 按鈕，一個預覽的郵件內容就會出現在下面的空白處。
最後我們需要在郵件通知的配置中應用這個模板。其實就是設定 Default Content 為：
${SCRIPT, template="groovy-html.template"}
好了，郵件的模板設定已經完成，趕快觸發個 Build 看看結果吧！

Pipeline 支援

Email Extension 外掛支援 pipeline， 下面的程式碼可以很好的工作：

stage('test') {
    steps {
        echo 'hello'
        // error 'build failed'
    }
    post {
        success {
            emailext (
              subject: "SUCCESSFUL: Job '${env.JOB_NAME} [${env.BUILD_NUMBER}]'",
              to: "nick@xxxxx.com",
              body: """<p>SUCCESSFUL: Job '${env.JOB_NAME} [${env.BUILD_NUMBER}]':</p>
    <p>Check console output at &QUOT;<a href='${env.BUILD_URL}'>${env.JOB_NAME} [${env.BUILD_NUMBER}]</a>&QUOT;</p>""",
              recipientProviders: [[$class: 'DevelopersRecipientProvider']]
            )
        }
        failure {
            emailext (
              subject: "FAILED: Job '${env.JOB_NAME} [${env.BUILD_NUMBER}]'",
              to: "nick@xxxxx.com",
              body: """<p>FAILED: Job '${env.JOB_NAME} [${env.BUILD_NUMBER}]':</p>
                <p>Check console output at &QUOT;<a href='${env.BUILD_URL}'>${env.JOB_NAME} [${env.BUILD_NUMBER}]</a>&QUOT;</p>""",
              recipientProviders: [[$class: 'DevelopersRecipientProvider']]
            )
        }
    }
}

上面的程式碼在 stage 執行成功或者失敗的情況下傳送郵件。但郵件的內容只是簡單的純文字或這是 HTML 格式的文字。筆者嘗試在 pipeline 程式碼中使用郵件模板的功能，但不管是 Jelly 模板還是 Groovy 模板都不能正常工作，所以這裡還有待完善的功能。

總結

Email Extension 是一款可定製性強、功能全面的 Jenkins 郵件通知外掛。隨著 pipeline 日漸成為主流的持續整合方式，希望能 Email Extension 也能緊跟趨勢提供對 pipeline 更好的支援。

相關文章