|
| 1 | +--- |
| 2 | +weight: 13 |
| 3 | +i18n: |
| 4 | + title: |
| 5 | + en: Configure Custom Mail Templates |
| 6 | +title: Configure Custom Mail Templates |
| 7 | +--- |
| 8 | + |
| 9 | +# Configure Custom Mail Templates |
| 10 | + |
| 11 | +## Introduction |
| 12 | + |
| 13 | +This guide explains how to add a new custom mail notification template for the `Send Mail` Task. |
| 14 | + |
| 15 | +## Scenarios |
| 16 | + |
| 17 | +For most use cases, use built-in templates first: |
| 18 | + |
| 19 | +- **Default Mail Template**: outputs basic information of the current PipelineRun. |
| 20 | +- **Custom Mail Template**: supports custom email content through provided template options. |
| 21 | + |
| 22 | +If built-in templates do not meet your requirements, follow this guide to create and configure a new template. |
| 23 | + |
| 24 | +## Prerequisites |
| 25 | + |
| 26 | +- `Send Mail` Task is available in your cluster. |
| 27 | +- You have permission to create `ConfigMap` in the target template namespace. |
| 28 | + |
| 29 | +## Template Support in Send Mail |
| 30 | + |
| 31 | +The `Send Mail` Task supports template-based rendering for `subject`, `body`, and `contentType`. |
| 32 | +By referencing a shared template `ConfigMap`, teams can maintain mail content globally and reuse the same template across multiple pipelines. |
| 33 | + |
| 34 | +For rendering workflow, built-in variables, and `renderTemplateValues` details, see [Supported Template Parameters for Tasks](./supported-template-parameters). |
| 35 | + |
| 36 | +## Steps |
| 37 | + |
| 38 | +### 1. Create a template ConfigMap |
| 39 | + |
| 40 | +Create a `ConfigMap` and set parameters as follows: |
| 41 | + |
| 42 | +Required parameters: |
| 43 | + |
| 44 | +- Label `tekton.alaudadevops.io/template-type: mail`: |
| 45 | + marks this `ConfigMap` as a mail template so the webhook can identify it as a render source for `Send Mail`. |
| 46 | +- Data keys `subject.tpl`, `body.tpl`, `contentType.tpl`: |
| 47 | + rendered with Go template (gotemplate) syntax and mapped to `subject`, `body`, and `contentType` params. |
| 48 | + For gotemplate syntax, see [Go `text/template` documentation](https://pkg.go.dev/text/template). |
| 49 | + For available template variables, see [Supported Template Parameters for Tasks](./supported-template-parameters). |
| 50 | + |
| 51 | +Optional parameters: |
| 52 | + |
| 53 | +- Annotation `tekton.alaudadevops.io/template-display-name`: |
| 54 | + human-readable name shown in UI selectors and preview panels. |
| 55 | +- Annotation `style.tekton.dev/descriptors`: |
| 56 | + defines a nested form for `renderTemplateValues` in UI, so users can fill template variables with form controls instead of manually editing YAML. For descriptor syntax and patterns, see [How to Configure Dynamic Forms](./configure_dynamic_forms.mdx). |
| 57 | + |
| 58 | +Example: |
| 59 | + |
| 60 | +```yaml |
| 61 | +apiVersion: v1 |
| 62 | +kind: ConfigMap |
| 63 | +metadata: |
| 64 | + name: release-mail-template |
| 65 | + namespace: kube-public |
| 66 | + labels: |
| 67 | + tekton.alaudadevops.io/template-type: mail |
| 68 | + annotations: |
| 69 | + tekton.alaudadevops.io/template-display-name: "Release Mail Template" |
| 70 | + style.tekton.dev/descriptors: | |
| 71 | + - path: params.extraMessage |
| 72 | + x-descriptors: |
| 73 | + - urn:alm:descriptor:label:en:Extra Message |
| 74 | + - urn:alm:descriptor:description:en:Additional message shown in mail body. |
| 75 | + - urn:alm:descriptor:com.tectonic.ui:text |
| 76 | + - urn:alm:descriptor:placeholder:en:Input an extra message |
| 77 | +data: |
| 78 | + subject.tpl: "PipelineRun {{ .context.pipelineRun.name }} - {{ .tasks.status }}" |
| 79 | + body.tpl: | |
| 80 | + PipelineRun: {{ .context.pipelineRun.name }} |
| 81 | + Status: {{ .tasks.status }} |
| 82 | + Message: {{ .values.extraMessage }} |
| 83 | + contentType.tpl: "text/plain; charset=UTF-8" |
| 84 | +``` |
| 85 | +
|
| 86 | +### 2. Configure pipeline to use your template |
| 87 | +
|
| 88 | +Set `renderTemplateName` and `renderTemplateNamespace`, then pass custom values through `renderTemplateValues`. |
| 89 | + |
| 90 | +```yaml |
| 91 | +apiVersion: tekton.dev/v1 |
| 92 | +kind: Pipeline |
| 93 | +metadata: |
| 94 | + name: demo-pipeline-with-mail-template |
| 95 | +spec: |
| 96 | + workspaces: |
| 97 | + - name: smtp-credentials |
| 98 | + tasks: |
| 99 | + - name: build |
| 100 | + taskRef: |
| 101 | + name: build-task |
| 102 | + finally: |
| 103 | + - name: notify |
| 104 | + taskRef: |
| 105 | + name: send-mail |
| 106 | + params: |
| 107 | + - name: sendMailImage |
| 108 | + value: registry.alauda.cn:60070/devops/tektoncd/hub/msmtp:latest |
| 109 | + - name: renderTemplateName |
| 110 | + value: release-mail-template |
| 111 | + - name: renderTemplateNamespace |
| 112 | + value: kube-public |
| 113 | + - name: renderTemplateValues |
| 114 | + value: | |
| 115 | + extraMessage: "Project: {{ .project }}, Namespace: {{ .namespace }}" |
| 116 | + - name: from |
| 117 | + value: no-reply@example.com |
| 118 | + - name: to |
| 119 | + value: |
| 120 | + - team@example.com |
| 121 | + workspaces: |
| 122 | + - name: smtp-credentials |
| 123 | + workspace: smtp-credentials |
| 124 | +``` |
| 125 | + |
| 126 | +### 3. Verify rendering results |
| 127 | + |
| 128 | +Check a mutated `TaskRun` and confirm `subject`, `body`, and `contentType` have been appended to `spec.params`. |
| 129 | + |
| 130 | +```yaml |
| 131 | +apiVersion: tekton.dev/v1 |
| 132 | +kind: TaskRun |
| 133 | +metadata: |
| 134 | + name: demo-pipeline-with-mail-template-notify |
| 135 | + namespace: demo |
| 136 | +spec: |
| 137 | + taskRef: |
| 138 | + name: send-mail |
| 139 | + params: |
| 140 | + - name: renderTemplateName |
| 141 | + value: release-mail-template |
| 142 | + - name: renderTemplateNamespace |
| 143 | + value: kube-public |
| 144 | + - name: renderTemplateValues |
| 145 | + value: | |
| 146 | + extraMessage: "Project: demo, Namespace: demo" |
| 147 | + - name: subject |
| 148 | + value: "PipelineRun demo-pipeline-run - Succeeded" |
| 149 | + - name: body |
| 150 | + value: | |
| 151 | + PipelineRun: demo-pipeline-run |
| 152 | + Status: Succeeded |
| 153 | + Message: Project: demo, Namespace: demo |
| 154 | + - name: contentType |
| 155 | + value: "text/plain; charset=UTF-8" |
| 156 | +``` |
| 157 | + |
| 158 | +If rendering fails, check TaskRun annotation `tekton.alaudadevops.io/template-render-error`. |
| 159 | + |
| 160 | +## FAQ |
| 161 | + |
| 162 | +### Do I have to configure `style.tekton.dev/descriptors`? |
| 163 | + |
| 164 | +No. It is optional. Configure it only when you want a structured UI form for `renderTemplateValues`. |
| 165 | + |
| 166 | +### Can I use both built-in variables and `values.xxx` in the same template? |
| 167 | + |
| 168 | +Yes. You can combine built-in variables (for example, `.context.pipelineRun.name`, `.tasks.status`) with user values such as `.values.extraMessage`. |
| 169 | + |
| 170 | +### What happens if `renderTemplateName` is not set? |
| 171 | + |
| 172 | +Template rendering is skipped. You need to provide `subject` and `body` params manually. |
| 173 | + |
| 174 | +### What should I check first when rendering does not work? |
| 175 | + |
| 176 | +1. Confirm `renderTemplateName` and `renderTemplateNamespace` point to an existing template `ConfigMap`. |
| 177 | +2. Confirm the `ConfigMap` includes label `tekton.alaudadevops.io/template-type: mail` and required keys `subject.tpl`, `body.tpl`, and `contentType.tpl`. |
| 178 | +3. Check TaskRun annotation `tekton.alaudadevops.io/template-render-error` for the concrete error message. |
0 commit comments