Jenkins - 邮件通知 Email Notification 插件

引言

利用 Jenkins 创建 Pipeline Job 来实现 CICD， 邮件通知每个 Job 的运行情况是非常有必要的。特别是测试，汇报测试用例执行结果，所以本文介绍一下有关 Jenkins 邮件通知插件，Mailer Plugin 和 Email Extension Plugin。

内容提要：

1. Email Plugin
   Mailer Plugin
   Email Extension Plugin
2. Email Notification Jenkins 系统配置
3. Email Extension Plugin 应用
4. TroubleShooting 故障排除

Email Plugin

主要介绍 2 个 Email Plugin，Mailer Plugin 和 Extended E-mail Notification Plugin

Mailer Plugin

安装 Jenkins 建议的 Plugin 后，默认会安装 Mailer Plugin，只是用来邮件通知 Build 结果，缺乏定制空间。

打开 Job Configure, 点开 Add post-build action 会看到 E-mail Notification 选项

添加 E-mail Notification 可配置的选项很少。

Email Extension Plugin

Email Extension Plugin 允许你全面灵活配置邮件通知，可以自定义邮件什么时候发送，谁应该收到邮件，邮件内容是啥。

通过 Manage Jenkins -> Plugin Manager 来安装该插件
安装成功后，打开 Job Configure 页面, 点开 Add post-build action 会看到 Editable Email Notification 选项

Email Notification Jenkins 系统配置

想通过 Jenkins 成功发送邮件，需要通过 Manage Jenkins -> Configure System 配置 SMTP 发件服务器 和 Admin 邮箱。

我配置的是 iCloud 邮箱，需要到 Apple 官网 找到适用于 iCloud 电子邮件客户端的邮件服务器设置。其他邮件也类似，找到对应的配置信息即可。

适用于发件服务器的 SMTP 信息 服务器名称：smtp.mail.me.com
是否需要 SSL：是 如果您在使用 SSL 时看到错误信息，请尝试使用 TLS 或 STARTTLS。
端口：587
是否需要 SMTP 鉴定：是
用户名：您的完整 iCloud 电子邮件地址（例如，[email protected]，而不是 emilyparker）
密码：使用您在设置收件服务器时生成的 App 专用密码。

各邮箱 smtp 服务器及支持的协议 有提到邮箱配置特别说明：
对于 ssl/tls 加密，使用 465 端口
对于 starttls 一般使用 587 端口

Mailer Plugin 的配置

在 E-mail Notifiction 部分，配置如下：

在 Jenkins Location 部分配置 Admin 邮箱，注意：不设置 Admin 邮箱无法发送邮件，这个 Admin 邮箱必须跟 SMTP authentication 配置中的发件人邮箱一致。

Email Extension Plugin 配置

在 Extended E-mail Notification 部分，SMTP 和 Admin 邮箱的设置跟 Mailer Plugin 一样，这里就不重复了。

还可以设置默认的收件人，回复人名单列表，当然如果在 Job Configure 中有配置会覆盖默认的设置，或则访问变量 $DEFAULT_RECIPIENTS 和 $DEFAULT_REPLYTO 直接用默认的设置。

默认的邮件 Subject 和 Content，同理 Job Configure 中的设置会覆盖默认的设置。

触发邮件通知的条件也可以被覆盖

点开 Content Token Reference 可以看到插件可用变量的说明，在定制邮件标题和内容时使用。请参考 Jenkins - 内置变量访问 文章中有专门列出邮件配置变量。

这里说一下常用的变量
Build 触发的起因，比如：可能是由某个 Pipeline job 触发的

邮件内容是来自某一文件的，这个比较常用，内容文件可以由脚本生成，注意 PATH 是 workspace 根目录的相对路径。

Email Extension Plugin 应用

在 Job Configure 中，Add build-post actions 添加 Editable Email Notification

注意：邮件附件，及内容文件的 PATH 都是基于 workspace 根目录的相对路径。如果邮件内容还内嵌图片，附件中也需要添加这个图片，生成的 html 内容中只需直接应用这个图片就可以了，不需要其它多余路径。

 <img src="cid:trend_image.png">

点击 Advance
设置邮件触发条件，Always 是不管 build 啥状态，都发送邮件通知。

设置收件人，这里有个小坑，默认可能会把 Developers 加上，导致每次收件人除了自定义的收件人列表，还加了其他人，这个其他人每天还是动态的，后面才发现这些动态的收件人其实是有提交 PR 代码改动的人。如果不想这些人收到邮件就得去掉。

下面这个就是应用后的邮件通知内容：出于内容敏感进行了模糊处理，了解大概内容就可以了

TroubleShooting 故障排除

通过任意 SMPT 服务需要 TLS 来发送邮件通知，默认 Jenkisn 是 Disable 了 mail.smtp.starttls 选项，我是通过 icloud SMTP 服务的，而且用的是 587 端口，这个是应用 starttls ，需要 Enable 这个选项。

如果 Disable 了这个选项，就会收到下面这个异常：
com.sun.mail.smtp.SMTPSendFailedException: 530 5.7.0 Must issue a STARTTLS command first

Windows 解决方案:

1. 打开 Jenkins 安装目录，可以通过 Jenkins UI 来知晓安装目录 Manage Jenkins 找到 Home directory 属性. 默认安装路径是 C:\Program Files (x86)\Jenkins
2. 打开 jenkins.xml 并添加 -Dmail.smtp.starttls.enable=true 在 arguments 部分

<executable>%BASE%\jre\bin\java</executable>
<arguments>-Xrs -Xmx256m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -Dmail.smtp.starttls.enable=true -jar "%BASE%\jenkins.war" --httpPort=8080 --webroot="%BASE%\war"</arguments>

4. 重启 Jenkins：通过URL {base_jenkins_url}/restart

Linux 解决方案请参考：Fixing SMTPSendFailedException on Ubuntu 16.04