定制通知模板

TeamCity 用户可以选择需要接收通知的事件。默认的通知消息可以在服务器级别进行全局自定义。

启用了 "更改项目中的用户 / 组通知规则" 权限的项目管理员可以编辑他们项目中分配给用户和用户组的通知规则。

通知生命周期

TeamCity 支持一组可以生成用户通知的事件（例如构建失败、调查状态更改等）。在事件发生时，TeamCity会为每种通知程序类型处理所有用户的通知设置，以确定需要通知哪些用户。

当确定用户集时，TeamCity 填充通知模型（与通知相关的对象，例如 "build" ，调查数据等），并评估与通知事件相对应的通知模板。
该模板使用数据模型对象生成输出值（例如，通知消息文本）。输出值随后被通知程序用来发送消息。每个通知程序支持一组特定的输出值。

请注意，模板对于一个事件只评估一次，这意味着通知属性无法按照每个用户进行调整。

模板定义的输出值随后被通知程序用来向选定的用户发送警报。

定制通知模板

通知模板位置

每个捆绑的 notifiers 都有一个在 <TeamCity 数据目录>/config/_notifications/ 的目录，存储 FreeMarker（ .ftl ）模板。还有.dist 文件，用来存储默认模板。每种通知类型都会评估一个对应名称的模板文件。模板文件可以在服务器运行时进行修改。

默认情况下，服务器每60秒检查一次文件中的更改，但可以通过将 teamcity.notification.template.update.interval internal property 设置为所需的秒数来更改这个设置。

如果在模板评估过程中出现错误，TeamCity 会将错误详细信息记录到 teamcity-notifications.log。可能会出现非关键性错误，导致部分模板被忽略，或是关键性错误，导致无法发送任何通知。无论何时您对通知模板进行更改，都要确保通知仍然可以发送。

这份文件并没有描述 FreeMarker 模板语言，所以如果您需要对 FreeMarker 语法的指导，可以参考相应的模板手册。

支持的输出值

TeamCity 通知程序使用模板来评估输出值（全局模板变量），然后通过名称检索这些值。支持以下的输出值：

电子邮件通知程序

主题 — 需要发送的电子邮件消息的主题
body—— 发送的电子邮件消息的纯文本内容
bodyHtml — （可选）要发送的电子邮件消息的 HTML 文本。它将与消息的纯文本部分一起包含。然而，如果它存在于模板中，那么也应该进行定制。
headers — （可选）要包含到电子邮件中的额外头部的原始列表。每行一个标题。例如：

<#global headers>
  X-Priority: 1 (Highest)
  Importance: High
</#global>

IDE 通知 和 Windows 托盘通知

message — 要发送的消息的纯文本
链接 — 包含有关事件详细信息的 TeamCity 页面的 URL

定制示例

此部分提供可用于定制通知的 Freemarker 代码片段：

包含日志中的错误

<#list build.buildLog.messages[1..] as message><#-- skipping the first message (it is a root node)-->
  <#if message.status == "ERROR" || message.status == "FAILURE" >
    ${message.text}
  </#if>
</#list>

以下示例显示了包含在 build_failed.ftl 模板中的片段：错误将在电子邮件的纯文本和 html 部分都列出：

<#-- Uses FreeMarker template syntax, template guide can be found at https://freemarker.org/docs/dgui.html -->
 
<#import "common.ftl" as common>
 
<#global subject>[<@common.subjMarker/> FAILED] ${project.name}:${buildType.name} - Build: ${build.buildNumber}</#global>
 
<#global body>TeamCity build: ${project.name}:${buildType.name} - Build: ${build.buildNumber} failed ${var.buildShortStatusDescription}.
Agent: ${agentName}
Build results: ${link.buildResultsLink}
 
${var.buildCompilationErrors}${var.buildFailedTestsErrors}${var.buildChanges}
 
 <#list build.buildLog.messages[1..] as message><#-- skipping the first message (it is a root node)-->
   <#if message.status == "ERROR" || message.status == "FAILURE" >
     ${message.text}
   </#if>
 </#list>
 
<@common.footer/></#global>
 
<#global bodyHtml>
<div>
  <div>
    TeamCity build: <i>${project.name}:${buildType.name} - <a href='${link.buildResultsLink}'>Build: ${build.buildNumber}</a></i> failed
    ${var.buildShortStatusDescription}
  </div>
  <@common.build_agent build/>
  <@common.build_comment build/>
  <br>
  <@common.build_changes var.changesBean/>
  <@common.compilation_errors var.compilationBean/>
  <@common.test_errors var.failedTestsBean/>
 
    <#list build.buildLog.messages[1..] as message><#-- skipping the first message (it is a root node)-->
   <#if message.status == "ERROR" || message.status == "FAILURE" >
     ${message.text}
   </#if>
 </#list>
 
  <@common.footerHtml/>
</div>
</#global>

列出构建工件

目前没有默认的方法可以在电子邮件模板中列出构建工件。参阅一个相关问题，其中包含一个简单的插件，通过相关 API 使您能够列出工件。

当前的解决方法

这假设模板可以直接访问磁盘，并忽略外部工件存储（如 S3）以及工件浏览策略（不显示内部工件）。另外，这种方式在未来的 TeamCity 版本中可能会被废弃。

<p>Build artifacts:</p>
  <#list build.artifactsDirectory.listFiles() as file>
    <a href="${webLinks.getDownloadArtefactUrl(build.buildTypeExternalId, build.buildId, file.name)}">${file.name}</a> (${file.length()}B)<br/>
  </#list>

这将仅列出根构件，并包括 .teamcity 目录，可以通过修改代码进行更改。

列出构建参数

<#list build.parametersProvider.all?keys as param>
  ${param} - ${build.parametersProvider.all[param]}
  <br>
</#list>

这将列出从服务器传递到构建的参数。

默认数据模型

对于模板评估，TeamCity 提供了可以在模板内部使用的默认数据模型。模型中暴露的对象是来自 TeamCity 服务器端开放 API 的相应类的实例。
可用对象模型的集合因事件的不同而不同。您也可以通过插件将自己的对象添加到模型中。请参阅扩展通知模板模型）以获取详细信息。

这是一个模型的示例描述（该代码可以在 IntelliJ IDEA 中用于编辑带有完成的模板）。请注意，下面列出的所有实体并非都会在任何模板中可用，例如，所有测试职责都在项目范围内分配，而且关于测试职责的通知可以配置为指向分配了调查的项目（而非构建配置）。

<#-- @ftlvariable name="project" type="jetbrains.buildServer.serverSide.SProject" -->
<#-- @ftlvariable name="buildType" type="jetbrains.buildServer.serverSide.SBuildType" -->
<#-- @ftlvariable name="build" type="jetbrains.buildServer.serverSide.SBuild" -->
<#-- @ftlvariable name="agentName" type="java.lang.String" -->
<#-- @ftlvariable name="buildServer" type="jetbrains.buildServer.serverSide.SBuildServer" -->
<#-- @ftlvariable name="webLinks" type="jetbrains.buildServer.serverSide.WebLinks" -->
 
<#-- @ftlvariable name="var.buildFailedTestsErrors" type="java.lang.String" -->
<#-- @ftlvariable name="var.buildShortStatusDescription" type="java.lang.String" -->
<#-- @ftlvariable name="var.buildChanges" type="java.lang.String" -->
<#-- @ftlvariable name="var.buildCompilationErrors" type="java.lang.String" -->
 
<#-- @ftlvariable name="link.editNotificationsLink" type="java.lang.String" -->
<#-- @ftlvariable name="link.buildResultsLink" type="java.lang.String" -->
<#-- @ftlvariable name="link.buildChangesLink" type="java.lang.String" -->
<#-- @ftlvariable name="responsibility" type="jetbrains.buildServer.responsibility.ResponsibilityEntry" -->
<#-- @ftlvariable name="oldResponsibility" type="jetbrains.buildServer.responsibility.ResponsibilityEntry" -->

TeamCity 通知属性

以下的 properties 可能对自定义通知行为有所帮助：

teamcity.notification.template.update.interval — 系统多久重新读取一次模板（整数，按秒计，默认 60）
teamcity.notification.includeDebugInfo — 在模板处理错误的情况下，将调试信息包含到消息中（布尔值，默认为 false）
teamcity.notification.maxChangesNum — 列在电子邮件消息中的最大更改数（整数，默认为10）
teamcity.notification.maxCompilationDataSize — 以字节为单位的编译错误数据的最大大小，以包含在电子邮件信息中（整数，默认值 20480）
teamcity.notification.maxFailedTestNum — 列在电子邮件消息中的失败测试的最大数量（整数，默认 50）
teamcity.notification.maxFailedTestStacktraces — 在电子邮件消息中的测试堆栈跟踪的最大数量（整数，默认 5）
teamcity.notification.maxFailedTestDataSize — 失败的测试输出数据在一封电子邮件消息中包含的最大大小（以字节为单位）（整数，默认 10240）

最后修改日期： 16日 7月 2024年