Send Notifications#
Taskcluster can send notifications when a task transitions states.
Notification Types#
There are four supported notification types:
Email - An email can be sent to any address.
Pulse - A pulse event can be triggered.
Matrix - A Matrix room can be pinged. Requires the Taskcluster deployment to be configured with Matrix credentials and be invited to the room.
Slack - A slack channel can be pinged. Requires the Taskcluster deployment to be configured with Slack credentials and be invited to the room.
Status Types#
A notification can be sent on the following task status changes:
on-defined
- When the task is first submitted to Taskcluster.on-pending
- When the task transitions to thepending
status.on-running
- When the task transitions to therunning
status.on-completed
- When the task finishes successfully.on-failed
- When the task finishes in thefailed
state.on-exception
- When the task finishes in theexception
state.on-resolved
- When the task finishes in any state.on-transition
- When any of the above are triggered.
Adding Notifications to a Task#
Taskgraph supports these notifications via the notify
transforms. Once these
have been added, a notify section can be used:
transforms:
- taskgraph.transforms.notify:transforms
tasks:
my-task:
# <rest of task definition>
notify:
recipients:
- type: email
address: list@example.com
status-type: on-resolved
- type: slack-channel
channel-id: KQP51F7GF
status-type: on-failed
The above task will notify the list@example.com
mailing list anytime the
task resolves for any reason, as well as ping the specified Slack channel
whenever the task fails. A Matrix room can be notified using type: matrix
and room-id: <id>
, and a pulse route can be notified using type: pulse
and routing-key: <key>
.
For each recipient, the status-type
key can be any one of the
aforementioned status types. If not specified, it
defaults to on-completed
.
Note
For a full reference, see the notify schema
.
Interpolating Recipients#
Each recipient value can be interpolated using Python’s format string syntax
and the task
and kind config
objects as
context. For example:
notify:
recipients:
- type: email
address: "{task[name]}-subscribers@example.com"
Custom Notification Content#
The example in the previous section would just send a generic message. You can
customize the content of your notifications using the content
subkey within
the notify
block, for example:
transforms:
- taskgraph.transforms.notify:transforms
tasks:
my-task:
# <rest of task definition>
notify:
recipients:
- type: email
address: list@example.com
status-type: on-resolved
- type: slack-channel
channel-id: KQP51F7GF
status-type: on-failed
content:
email:
subject: "A task has completed!"
slack:
text: "A task has failed!"
Each notification type has its own way of specifying content:
Email#
Supports the following keys:
subject
- The subject of the email.content
- The body of the email (markdown supported).link
- An object of the form{"text": <text>, "href": <url>}
which will add a button to the email with the specified text and linking to the specified url.
Matrix#
Supports the following keys:
body
- The plain text body of the message.formatted-body
- A rich text message. If a client is unable to render this, the notification will fallback to the text inbody
.format
- The format of theformatted-body
key, e.gorg.matrix.custom.html
.msg-type
- The type of Matrix message to send, e.gm.notice
(default).
Slack#
Supports the following keys:
text
- The simple text field for the message. Supports Slack-flavored markdown.blocks
- A list of block objects conforming to Slack’s blocks format. Iftext
is also specified,text
will only be used as a fallback.attachments
- A list of attachment objects conforming to Slack’s attachments format.
Note
Taskcluster does not support different content between recipients of the same type.
Interpolating Content#
But specifying content as a plain string isn’t be very useful. You’ll want to add some context to your content!
Similar to recipients, each content value can be interpolated using Python’s
format string syntax and the task
and kind config
objects as context.
Taskcluster also supports JSON-e in any of these keys which can be useful to
interpolate values that are not known at Taskgraph run time (like the
taskId
or status of the task).
For example:
notify:
content:
slack:
text: "{task[name]} with id $taskId has finished!"
In the above example, {task[name]}
will be interpolated locally
by Taskgraph, whereas $taskId
will be interpolated by Taskcluster using
JSON-e.
Of course it’s also possible to perform your own more advanced interpolation in a transform! E.g, you could implement a dedicated notify task which links to artifacts from multiple dependencies.