go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/luci_notify/doc/email_templates.md (about)

     1  # Email templates
     2  
     3  Users of luci-notify service can define custom email templates.
     4  A notifier configuration or a build can specify the template to be used when
     5  generating an email.
     6  
     7  [TOC]
     8  
     9  ## Directory/File structure
    10  
    11  Templates live in a project configuration directory.
    12  You can locate your configuration directory in
    13  `https://luci-config.appspot.com/#/projects/$LUCI_PROJECT`.
    14  Browsing [luci-config.appspot.com](https://luci-config.appspot.com) may also
    15  help.
    16  
    17  A luci-notify service hosted at `<appid>.appspot.com` reads all files matching
    18  `<appid>/email-templates/<template_name>.template`.
    19  The prod app id is `luci-notify`.
    20  `<template_name>` must match regexp `^[a-z][a-z0-9\_]*$`.
    21  Example:
    22  
    23  * luci-notify/email-templates/default.template
    24  * luci-notify/email-templates/fancy.template
    25  
    26  Each file must be have format `<subject>\n\n<body>`, where subject is
    27  one line of [text/template](https://godoc.org/text/template) and body is an
    28  [html/template](https://godoc.org/html/template).
    29  
    30  Template `default` is used if template is not specified.
    31  
    32  Note `<appid>.cfg` project config is still required, even if it does not define
    33  any notifiers.
    34  
    35  ## Template input
    36  
    37  The input to both templates is a [TemplateInput](https://godoc.org/go.chromium.org/luci/luci_notify/api/config#TemplateInput)
    38  Go struct derived from [TemplateInput](https://cs.chromium.org/chromium/infra/go/src/go.chromium.org/luci/luci_notify/api/config/notify.proto?q=TemplateInput)
    39  proto message.
    40  
    41  ## Template functions
    42  
    43  The following functions are available to templates in addition to the
    44  [standard ones](https://godoc.org/text/template#hdr-Functions).
    45  
    46  * `time`: converts a
    47    [Timestamp](https://pkg.go.dev/google.golang.org/protobuf/types/known/timestamppb#Timestamp)
    48    to [time.Time](https://godoc.org/time).
    49    Example: `{{.Build.EndTime | time}}`
    50  * `formatBuilderID`: converts a
    51    [BuilderID](https://godoc.org/go.chromium.org/luci/buildbucket/proto#BuilderID)
    52    to a `<project>/<bucket>/<builder>` string.
    53    Example: `{{.Build.Builder | formatBuilderID}}`
    54  * `markdown`: converts a presumed Markdown string to safe HTML.
    55    Example: `{{.Build.SummaryMarkdown | markdown}}`
    56  * `stepNames`: converts a
    57    [`[]*Step`](https://godoc.org/go.chromium.org/luci/buildbucket/proto#Step) to
    58    a comma-separated list of quoted step names.
    59    Example: `{{.MatchingFailedSteps | stepNames}}`
    60  * `buildUrl`: converts the entire
    61    [TemplateInput](https://godoc.org/go.chromium.org/luci/luci_notify/api/config#TemplateInput)
    62    into a URL pointing to the milo page for the build in question.
    63    Example: `{{. | buildUrl}}`
    64  
    65  ## Template example
    66  
    67  ```html
    68  A {{.Build.Builder | formatBuilderID}} build completed
    69  
    70  <a href="https://{{.BuildbucketHostname}}/builds/{{.Build.Id}}">Build {{.Build.Number}}</a>
    71  has completed with status {{.Build.Status}}
    72  on `{{.Build.EndTime | time}}`
    73  ```
    74  
    75  ## Template sharing
    76  
    77  One file can define subtemplates and another file can reuse them.
    78  When rending, all template files are merged into one. Example:
    79  
    80  
    81  luci-notify/email-templates/default.template:
    82  
    83  ```html
    84  A {{.Build.Builder | formatBuilderID}} completed
    85  
    86  A <a href="https://{{.BuildbucketHostname}}/builds/{{.Build.Id}}">build</a> has completed.
    87  
    88  Steps: {{template "steps" .}}
    89  
    90  {{template "disclaimer"}}
    91  ```
    92  
    93  luci-notify/email-templates/steps.template:
    94  
    95  ```html
    96  This template renders only steps. It is used by other files.
    97  
    98  {{range $step := .Build.Steps}}
    99    <li>{{$step.name}}</li>
   100  {{end}
   101  ```
   102  
   103  luci-notify/email-templates/common.template:
   104  
   105  ```html
   106  This file defines subtemplates used by other files.
   107  
   108  {{define "disclaimer"}}
   109    Disclaimer: luci-notify does not take any responsibility for the build result.
   110  {{end}}
   111  ```
   112  
   113  ## Email preview
   114  
   115  [preview_email](http://godoc.org/go.chromium.org/luci/luci_notify/cmd/preview_email)
   116  command can render a template file to stdout.
   117  
   118  Example:
   119  
   120  ```shell
   121    bb get -json -A 8914184822697034512 | preview_email ./default.template
   122  ```
   123  
   124  This example uses bb tool, available in
   125  [depot_tools](https://chromium.googlesource.com/chromium/tools/depot_tools/).
   126  
   127  Command `preview_email` is available in
   128  [infra Go env](https://chromium.googlesource.com/infra/infra/+/HEAD/go/README.md)
   129  and as a
   130  [CIPD package](https://chrome-infra-packages.appspot.com/p/infra/tools/preview_email).
   131  
   132  ## Error handling
   133  
   134  If a user-defined template fails to render, an built-in template is used
   135  to generate a very short email with a link to the build and details about the
   136  failure.