Alauda DevOps Artifact Hub Shim Docs
  • 简体中文

    • 配置自定义邮件模板

    目录

    简介适用场景前提条件Send Mail 中的模板支持步骤1. 创建模板 ConfigMap2. 配置 pipeline 以使用你的模板3. 验证渲染结果FAQ我必须配置 style.tekton.dev/descriptors 吗？我能在同一个模板中同时使用内置变量和 values.xxx 吗？如果未设置 renderTemplateName 会发生什么？模板 ConfigMap 应该使用哪个命名空间？当渲染不生效时，我应该先检查什么？

    简介

    本指南说明如何为 Send Mail Task 添加新的自定义邮件通知模板。

    适用场景

    对于大多数使用场景，请先使用内置模板：

    • 默认邮件模板：输出当前 PipelineRun 的基本信息。
    • 自定义邮件模板：通过提供的模板选项支持自定义邮件内容。

    如果内置模板无法满足你的需求，请按照本指南创建并配置新模板。

    前提条件

    • 你的集群中可用 Send Mail Task。
    • 已启用 artifacthub-shim-extension template-render webhook。
    • 你有在目标模板命名空间中创建 ConfigMap 的权限。

    Send Mail 中的模板支持

    Send Mail Task 支持对 subject、body 和 contentType 进行基于模板的渲染。
    通过引用共享模板 ConfigMap，团队可以全局维护邮件内容，并在多个 pipeline 中复用同一模板。

    有关渲染工作流、内置变量以及 renderTemplateValues 的详细信息，请参见 Tasks 的支持模板参数。

    步骤

    1. 创建模板 ConfigMap

    创建一个 ConfigMap，并按如下方式设置参数：

    推荐命名空间：

    • 尽可能将模板 ConfigMap 放在 kube-public 中。kube-public 是常用的共享命名空间，便于来自不同命名空间的 TaskRun 资源复用同一模板。
    • 如果你将模板存储在其他命名空间中，请在 Task/Pipeline 参数中显式将 renderTemplateNamespace 设置为该命名空间。详情请参见 Tasks 的支持模板参数。

    必需参数：

    • 标签 tekton.alaudadevops.io/template-type: mail： 将此 ConfigMap 标记为邮件模板，以便 webhook 可以将其识别为 Send Mail 的渲染源。
    • 数据键 subject.tpl、body.tpl、contentType.tpl： 使用 Go template（gotemplate）语法进行渲染，并分别映射到 subject、body 和 contentType 参数。 关于 gotemplate 语法，请参见 Go text/template 文档。 关于可用模板变量，请参见 Tasks 的支持模板参数。

    可选参数：

    • 注解 tekton.alaudadevops.io/template-display-name： 在 UI 选择器和预览面板中显示的人类可读名称。
    • 注解 style.tekton.dev/descriptors： 为 UI 中的 renderTemplateValues 定义嵌套表单，使用户可以通过表单控件填写模板变量，而不是手动编辑 YAML。

    示例：

    apiVersion: v1
kind: ConfigMap
metadata:
  name: release-mail-template
  namespace: kube-public
  labels:
    tekton.alaudadevops.io/template-type: mail
  annotations:
    tekton.alaudadevops.io/template-display-name: "Release Mail Template"
    style.tekton.dev/descriptors: |
      - path: params.extraMessage
        x-descriptors:
          - urn:alm:descriptor:label:en:Extra Message
          - urn:alm:descriptor:description:en:Additional message shown in mail body.
          - urn:alm:descriptor:com.tectonic.ui:text
          - urn:alm:descriptor:placeholder:en:Input an extra message
data:
  subject.tpl: "PipelineRun {{ .context.pipelineRun.name }} - {{ .tasks.status }}"
  body.tpl: |
    PipelineRun: {{ .context.pipelineRun.name }}
    Status: {{ .tasks.status }}
    Message: {{ .values.extraMessage }}
  contentType.tpl: "text/plain; charset=UTF-8"

    2. 配置 pipeline 以使用你的模板

    设置 renderTemplateName 和 renderTemplateNamespace，然后通过 renderTemplateValues 传递自定义值。

    apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: demo-pipeline-with-mail-template
spec:
  workspaces:
    - name: smtp-credentials
  tasks:
    - name: build
      taskRef:
        name: build-task
  finally:
    - name: notify
      taskRef:
        name: send-mail
      params:
        - name: sendMailImage
          value: registry-dev.alauda.io/alauda-pipelines-catalog/hub/msmtp:latest
        - name: renderTemplateName
          value: release-mail-template
        - name: renderTemplateNamespace
          value: kube-public
        - name: renderTemplateValues
          value: |
            extraMessage: "Project: {{ .project }}, Namespace: {{ .namespace }}"
        - name: from
          value: no-reply@example.com
        - name: to
          value:
            - team@example.com
      workspaces:
        - name: smtp-credentials
          workspace: smtp-credentials

    3. 验证渲染结果

    检查变异后的 TaskRun，并确认 subject、body 和 contentType 已追加到 spec.params 中。

    apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: demo-pipeline-with-mail-template-notify
  namespace: demo
spec:
  taskRef:
    name: send-mail
  params:
    - name: renderTemplateName
      value: release-mail-template
    - name: renderTemplateNamespace
      value: kube-public
    - name: renderTemplateValues
      value: |
        extraMessage: "Project: demo, Namespace: demo"
    - name: subject
      value: "PipelineRun demo-pipeline-run - Succeeded"
    - name: body
      value: |
        PipelineRun: demo-pipeline-run
        Status: Succeeded
        Message: Project: demo, Namespace: demo
    - name: contentType
      value: "text/plain; charset=UTF-8"

    如果渲染失败，请检查 TaskRun 注解 tekton.alaudadevops.io/template-render-error。

    FAQ

    我必须配置 style.tekton.dev/descriptors 吗？

    不需要。它是可选的。只有在你希望为 renderTemplateValues 提供结构化 UI 表单时才需要配置。

    我能在同一个模板中同时使用内置变量和 values.xxx 吗？

    可以。你可以将内置变量（例如 .context.pipelineRun.name、.tasks.status）与用户值（例如 .values.extraMessage）结合使用。

    如果未设置 renderTemplateName 会发生什么？

    模板渲染会被跳过。你需要手动提供 subject 和 body 参数。

    模板 ConfigMap 应该使用哪个命名空间？

    尽可能使用 kube-public。这是一个常见的共享命名空间，便于跨不同命名空间的 TaskRun 资源复用同一模板。

    如果模板 ConfigMap 存储在其他命名空间中，请显式将 renderTemplateNamespace 设置为该命名空间。有关参数详情，请参见 Tasks 的支持模板参数。

    当渲染不生效时，我应该先检查什么？

    1. 确认 renderTemplateName 和 renderTemplateNamespace 指向一个存在的模板 ConfigMap。
    2. 确认该 ConfigMap 包含标签 tekton.alaudadevops.io/template-type: mail，以及必需的键 subject.tpl、body.tpl 和 contentType.tpl。
    3. 查看 TaskRun 注解 tekton.alaudadevops.io/template-render-error，获取具体错误信息。