Jenkins : 邮件通知

Posted 2020-10-03 sparkdev

目录

• 全局配置
• 为项目添加邮件通知
• 邮件模板
• Pipeline 支持
• 总结

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: "[e-mail]",
              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: "[e-mail]",
              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 更好的支持。