Jenkins Email Extension 插件

• Email Extension
  • 介绍
  • 问题和议题
  • 入门
    • 系统范围的配置
    • 项目配置
  • 流水线步骤
  • 用法
    • 预发送脚本和后发送脚本
  • 触发器
    • 扩展电子邮件发布者触发器
    • 常用触发选项
  • 脚本触发器选项
  • Tokens
  • Jelly 脚本内容模板
  • Groovy 脚本内容模板
  • 附件
  • Jive 格式化程序

Email Extension

官网地址：Email Extension

介绍

这个插件通过给您更多的控制来扩展 Mailer 插件的功能。它提供了三个区域的定制：

Triggers（触发器）

选择应导致发送电子邮件通知的条件。

Content（内容）

指定每个触发电子邮件的主题和正文的内容。

Recipients（收件人）

指定触发电子邮件时应该接收电子邮件的人。

问题和议题

在 Jenkins 问题跟踪器中报告错误和增强请求（请不要支持票证）。使用项目 email-ext-plugin 中的组件 JENKINS。

入门

系统范围的配置

在项目中使用此插件之前，您必须首先配置一些系统范围的设置。转到 Jenkins 系统范围的配置页面（管理 Jenkins，配置系统）。

这个插件的配置可以在 扩展电子邮件通知 部分找到。此配置应与您的 SMTP 邮件服务器的设置相匹配。此部分反映了电子邮件通知部分中的 Mailer 插件；但是，还有一些补充。标有 默认主题 和 默认内容 的字段允许您在系统范围内配置主题和内容。标记为 Default Recipients 的字段可用于设置使用此插件的所有项目的默认电子邮件地址列表（并且可以在项目级别覆盖）；这可用于大大简化您需要为所有项目进行的配置。

项目配置

项目要使用该插件，需要在项目配置页面中启用。在 Post-build Actions 部分，单击 Add post-build action，然后选择 Editable Email Notification。

启用此插件后，您可以编辑三个主要字段：

Project Recipient List（项目收件人名单）

这是一个逗号（或空格）分隔的电子邮件收件人列表。允许您为发送的每封电子邮件指定一个收件人列表。

Default Subject（默认主题）

这允许您配置一个令牌（稍后将详细介绍令牌），该令牌可用于轻松配置项目的所有电子邮件主题。

Default Content（默认内容）

与 Default Subject 相同，但用于电子邮件正文而不是主题。

流水线步骤

可以通过以下步骤从 Pipeline 使用此插件：emailext

emailext body: 'Test Message',
    subject: 'Test Subject',
    to: 'test@example.com'

使用 recipientProviders 参数添加其他收件人。例如：要添加导致变更集中发生变更的所有人员以及发起构建的用户：

emailext body: 'Test Message',
    recipientProviders: [developers(), requestor()],
    subject: 'Test Subject',
    to: 'test@example.com'

此插件的收件人提供程序也可以与 Mailer 插件一起使用。例如：添加罪魁祸首和发起构建的用户：

step([$class: 'Mailer',
    notifyEveryUnstableBuild: true,
    recipients: emailextrecipients([culprits(), requestor()])])

用法

要查看此插件的高级配置，请单击高级按钮。此部分允许您为每种类型的电子邮件触发器指定收件人以及可用于在发送之前修改电子邮件的预发送脚本。

预发送脚本和后发送脚本

此功能允许您编写 MimeMessage 可以在发送电子邮件之前或之后修改对象的脚本。这允许添加自定义标题、修改正文等。预定义的变量包括：

msg( jakarta.mail.internet.MimeMessage)

MIME 电子邮件消息对象，可以修改。

logger( java.io.PrintStream)

可用于将消息记录到构建日志的 PrintStream 。

build( hudson.model.AbstractBuild)

此消息所属的构建（仅用于 Freestyle 项目）。

run( hudson.model.Run)

此消息所属的构建（可与 Freestyle 项目或 Pipeline 一起使用）。

cancel（布尔值）

当设置为 true 时，取消电子邮件的发送。

触发器

默认情况下，唯一配置的触发器是 Failure - Any 触发器。要添加更多触发器，请从下拉列表中选择一个，它将被添加到列表中。要查看此插件发送电子邮件必须满足哪些条件，请单击 ？ （问号）旁边的触发器。

扩展电子邮件发布者触发器

以下触发器可作为 Extended Email Publisher 插件的一部分使用，其他插件也可以通过 Extended Email Publisher 中定义的扩展点提供触发器：

Aborted（中止）

如果构建状态为 “Aborted”，将发送一封电子邮件。构建通过 UI 或 API 中止，但通常需要某种用户干预才能发生。中止的构建在其执行期间停止。

Always（总是）

无论构建状态如何，始终在构建后触发电子邮件。

Before Build（构建之前）

构建开始时将发送一封电子邮件，但在 SCM 轮询完成之后。

Failure → Unstable (Test Failures)（失败→不稳定（测试失败））

每当构建从失败（编译或构建步骤失败）变为不稳定（单元测试失败）时，都会发送一封电子邮件。这基本上意味着所有的构建步骤都成功了，但仍然有测试失败。

Failure - Any（失败 - 任何）

任何时候构建失败都会发送一封电子邮件。如果配置了 “Failure - Still” 触发器，并且之前的构建状态为 “Failure”，则 “Failure - Still” 触发器将改为发送电子邮件。

Failure - 1st（失败 - 第一次）

当构建状态从 “Success” 变为 “Failure” 时，将发送一封电子邮件。

Failure - 2nd（失败 - 第二次）

构建成功后，如果连续两次构建失败，将发送一封电子邮件。

Failure - Still（失败 - 仍然）

如果连续两个或多个构建的构建状态为 “Failure”，则会发送一封电子邮件。

Failure - X（失败 - X）

构建成功后连续 X 次构建失败时会发送一封电子邮件

Fixed（固定的）

当构建状态从 “Failure” 或 “Unstable” 变为 “Success” 时，将发送一封电子邮件。

Not Built（未建）

如果构建状态为 “Not Built”，将发送一封电子邮件。此状态代码用于多阶段构建（如：maven2），其中早期阶段的问题阻止了后期阶段的构建。

Script - After Build（脚本 - 构建后）

允许用户定义一个脚本，该脚本被执行以确定是否应该在构建发生后发送电子邮件。脚本的最后一行应解析为 true 以发送电子邮件，或 false 以不发送电子邮件。有关脚本可用的参数，请参阅下面的脚本触发器选项。

Script - Before Build（脚本 - 构建之前）

允许用户定义一个脚本，该脚本被执行以确定是否应该在构建发生之前发送电子邮件。脚本的最后一行应解析为 true 以发送电子邮件，或 false 以不发送电子邮件。有关脚本可用的参数，请参阅下面的脚本触发器选项。

Status Changed（状态已更改）

如果构建状态发生变化，将发送一封电子邮件。

Success（成功）

如果构建状态为 “Success”，将发送一封电子邮件。如果配置了 “Fixed” 触发器，并且之前的构建状态为 “Failure” 或 “Unstable”，则 “Fixed” 触发器将改为发送电子邮件。

Test Improvement（测试改进）

只要有改进，就会发送一封电子邮件。只要测试失败的次数少于之前的版本，就认为该版本已改进。如果当前失败计数变为 0（不再有测试失败），此触发器将不会发送电子邮件。

Test Regression（测试回归）

只要有回归，就会发送一封电子邮件。每当一个构建的失败比之前的构建多，或者有新的测试失败时，它就会被认为是倒退。

Unstable (Test Failures)（不稳定（测试失败））

每当构建不稳定时，都会发送一封电子邮件。如果测试失败，则构建不稳定，但所有构建步骤均已成功完成。如果配置了 “Unstable - Still” 触发器，并且之前的构建状态为 “Unstable”，则 “Unstable - Still” 触发器将改为发送电子邮件。

Unstable (Test Failures) - 1st（不稳定（测试失败） - 第一）

当构建状态从任何更改为 “Unstable” 时，将发送一封电子邮件。

Unstable (Test Failures) - Still（不稳定（测试失败） - 仍然）

如果连续两个或多个构建的构建状态为 “Unstable”，则会发送一封电子邮件。如果测试失败，则构建不稳定，但所有构建步骤均已成功完成。

Unstable (Test Failures)/Failure → Success（不稳定（测试失败）/失败→成功）

当构建状态从 “Failure” 或 “Unstable” 变为 “Success” 时，将发送一封电子邮件。中间的 “Aborted” 构建被忽略。

常用触发选项

添加触发器后，您有几个常用选项（可能还有其他选项可用，具体取决于触发器实现）：

Recipient List（收件人名单）

如果您希望将电子邮件发送到上面配置的项目收件人列表，请添加此收件人提供商。

Developers（开发者）

添加此收件人提供商以将电子邮件发送给签入上次构建代码的任何人。此插件将根据提交者的 ID 和配置系统页面的扩展电子邮件通知部分附加的默认用户电子邮件后缀生成一个电子邮件地址。例如：如果某个 ID 为 first.last 的人提交了更改，并且默认用户电子邮件后缀是 @example.com，那么将向 first.last@example.com 发送一封电子邮件。

Requestor（请求者）

添加此收件人提供程序以向启动构建的用户发送电子邮件（如果由用户手动启动）。

Include Culprits（包括罪魁祸首）

如果添加了此收件人提供者和 Developers 收件人提供者，电子邮件将包括自上次成功构建以来提交的每个人。

Previous（以前的）

添加此收件人提供商以向先前构建的罪魁祸首、请求者和开发人员发送电子邮件。

Advanced（先进的）

在每个触发器级别配置属性

Recipient List（收件人名单）

一个逗号（或空格）分隔的电子邮件地址列表，如果它被触发，则应接收此电子邮件。此列表附加到上述项目接收者列表中。

Subject（主题）

指定所选电子邮件的主题行。

Content（内容）

指定所选电子邮件的正文。

脚本触发器选项

您还可以将 Script - After Build 或 Script - Before Build 触发器添加到项目中，以使用 Groovy 脚本在构建之前或之后定义是否发送电子邮件。该脚本在触发器的 Groovy Script 部分中定义。模型中添加了四个对象，脚本用于与构建进行交互：

out( java.io.PrintStream)

可用于将消息记录到构建日志的 PrintStream。

build( hudson.model.AbstractBuild)

这是当前的构建，通常是 AbstractBuild。

project( hudson.model.AbstractProject)

当前构建开始的项目对象，通常是 AbstractProject。

rooturl( String)

Jenkins 实例根 URL，对链接很有用。

脚本中的最后一行应解析为布尔值（true 或 false）：

脚本 - 构建之前：

// this could be used to notify people that a new build is happening
build.previousBuild.result.toString().equals('FAILURE')

脚本 - 构建后：

// only send am email if the build failed and 'mickeymouse' had a commit
build.result.toString().equals('FAILURE') && build.hasParticipant(User.get('mickeymouse'))

// only send an email if the word {{ERROR}} is found in build logs
build.logFile.text.readLines().any { it =~ /.*ERROR.*/ }

Tokens

该插件使用令牌允许将动态数据插入收件人列表、主题行或正文中。标记是一个以 $</kbd>（美元符号）开头并以空格结尾的字符串。触发电子邮件时，主题或内容字段中的标记将被它所代表的实际值动态替换。此外，令牌的值可以包含其他令牌，这些令牌本身将被实际内容替换。例如：该‘$DEFAULT_SUBJECT标记被 “配置系统” 页面的 “扩展电子邮件通知” 部分的 “默认主题” 字段中的文本（和其他标记）替换。同样，令牌将被替换为$PROJECT_DEFAULT_SUBJECT` 项目配置页面中的默认主题字段。

当您为项目启用电子邮件内容字段时，该插件将其设置为默认值。项目配置页面上的默认主题和默认内容字段分别默认为 $DEFAULT_SUBJECT 和 $DEFAULT_CONTENT，从配置系统页面的扩展电子邮件通知部分委托给系统范围的配置。类似地，每个触发器内容字段默认为 $PROJECT_DEFAULT_SUBJECT 和 $PROJECT_DEFAULT_CONTENT，委托给项目的配置。由于令牌的值可以包含其他令牌，因此这提供了不同的配置点，允许您在最广泛的级别（所有项目）、最狭窄的级别（单个电子邮件）和中间级别（单个项目）快速进行更改。

要查看所有可用电子邮件令牌的列表及其显示的内容，请单击 ？（问号）与项目配置页面的可编辑电子邮件通知部分中的内容令牌参考相关联。

从 2.22 版本开始，该插件还支持 Token Macro 插件提供的令牌。当您单击 ？（问号）时，您可以在扩展电子邮件发布者特定令牌下方看到可用的令牌宏插件令牌。与项目配置页面的可编辑电子邮件通知部分中的内容令牌参考相关联。

Jelly 脚本内容模板

2.9 版的新功能是可以使用 Jelly 脚本。Jelly 脚本的强大之处在于您可以连接到 Jenkins API 以获取您想要或需要的任何信息。这个插件打包了两个 Jelly 脚本，也可以自己写。

有两个开箱即用的默认 Jelly 脚本；一种是为 HTML 电子邮件设计的，另一种是为文本电子邮件设计的。您可以使用 template 参数指定您想要的脚本。每种脚本的用法如下：

Text-only Jelly script

${JELLY_SCRIPT,template="text"}

HTML Jelly script

${JELLY_SCRIPT,template="html"}

您还可以编写自己的 Jelly 脚本。Jelly 脚本特别强大，因为它们提供了 Jenkins API 的挂钩，包括 hudson.model.AbstractBuild 和 hudson.model.AbstractProject。有关如何执行此操作的示例，请查看现有 html 和 text 脚本。

使用自定义 Jelly 脚本（未与此插件打包的脚本）需要您的 Jenkins 管理员的合作。步骤比较简单：

1. 创建 Jelly 脚本模板。脚本的名称应该是 <name>.jelly。

名称以 .jelly 结尾很重要。

2. 让您的 Jenkins 管理员将脚本放入 ${JENKINS_HOME}/email-templates/。

3. 使用 $JELLY_SCRIPT 令牌，template 参数等于脚本文件名，不带 .jelly 扩展名。例如：如果脚本文件名为 foobar.jelly，电子邮件内容将是 ${JELLY_SCRIPT,template="foobar"}。

您可以通过查询构建操作来获取其他插件操作的对象，例如：${it.getAction('hudson.plugins.fitnesse.FitnesseResultsAction')}。然后您需要知道这个动作对象允许哪些功能，并遍历结果。

Groovy 脚本内容模板

2.15 版的新功能是使用 Groovy 脚本的能力。脚本的强大之处在于您可以连接到 Jenkins API 以获取您想要或需要的任何信息。这个插件有两个脚本和对应的模板打包，也可以自己写。

有两个开箱即用的默认脚本和模板；一种是为 HTML 电子邮件设计的，另一种是为文本电子邮件设计的。您可以使用 script 参数指定您想要的脚本；您还可以保留默认脚本并使用 template 参数指定不同的模板文件。此外，您还可以包含一个使用该 init 参数进行一些初始化的脚本。每种脚本的用法如下：

Text-only Groovy script

${SCRIPT, template="groovy-text.template"}

HTML Groovy script

${SCRIPT, template="groovy-html.template"}

您还可以编写自己的脚本和模板。这些脚本特别强大，因为它们提供了 Jenkins API 的挂钩，包括 hudson.model.AbstractBuild 和 hudson.model.AbstractProject。有关如何执行此操作的示例，请查看现有 html 和 text 脚本。

使用自定义脚本（未与此插件打包的脚本）需要您的 Jenkins 管理员的合作。步骤比较简单：

1. 创建 Groovy 脚本模板。脚本名称以语言的标准扩展名结尾（即 .groovy）。模板可以命名为任何名称。

2. 让您的 Jenkins 管理员将脚本放入 ${JENKINS_HOME}/email-templates/。

3. 使用 $SCRIPT 模板参数等于您的模板文件名的令牌，或者另外使用等于自定义脚本名称的脚本参数。例如：如果模板文件名为 foobar.template，则电子邮件内容将为 ${SCRIPT, template="foobar.template"}。

请参阅以下示例以使用内置 Groovy 模板执行各种操作：

• jenkins-matrix-email-html.template
• jenkins-generic-matrix-email-html.template

附件

2.15 版的新增功能是能够使用 Jenkins 中许多地方使用的 Ant 模式匹配语法添加附件。您可以在 配置系统 页面的 扩展电子邮件通知 部分设置最大总附件大小；否则，它将是无限的。

Jive 格式化程序

jive-formatter.groovy 包含用于轻松方便地格式化从 Jenkins 发送到 Jive 的电子邮件的方法。它应该从 Pre-send Script 区域调用。

Jive 似乎不支持多种格式的文本，因此每个文本块只调用一种格式化方法。

在调用颜色或大小等格式化方法之前，将在发送到 Jive 系统的每一行文本上调用 formatLine 或 formatText 可以并且应该调用。请在您自己的 Jive 实例上进行测试，并在发现时添加功能！

在尝试调用任何函数之前，应将以下行添加到 Pre-send Script 区域：

File sourceFile = new File("/your/preferred/path/jive-formatter.groovy");
Class groovyClass = new GroovyClassLoader(getClass().getClassLoader()).parseClass(sourceFile);
GroovyObject jiveFormatter = (GroovyObject) groovyClass.newInstance();