Triggers

Triggers are reactions to events on an activity. Each trigger has an event (when it fires), optional conditions (whether it fires), and one or more actions (what it does).

Skeleton

triggers:
  - onCreate:
      - alert: ${__channel} ${initiator}
  - onComment:
      - agent: triage
      - script: extract-jira-ids
  - onEdit:
      - attribute: severity
        ifMatch: critical
        alert: "#oncall"
  - onConclude:
      - email:
          to: ${initiator}
          subject: "Resolved: ${title}"
          body: ${conclusion}

triggers: is a list of trigger groups, each containing one or more trigger lists keyed by event. (Most apps only need one group.)

Events

onCreate and onConclude fire once per activity. onComment and onEdit fire repeatedly. Triggers also fire from clicked buttons, but those are attached to the attribute, not to an event list — see Attributes.

Conditions

- attribute: status
  ifMatch: "^(open|in_progress)$"
  alert: "#team"

For an onComment trigger, ifMatch is checked against the comment text:

onComment:
  - ifMatch: "^(?i)help\\s*$"
    agent: helper

Actions

A trigger can carry one or more of these actions, all inlined into the same trigger:

- alert: "#oncall"
  owner: ${initiator}
  setAttribute:
    name: priority
    value: high
  message:
    to: "#announcements"
    body: "${title} acknowledged by ${owner}"

setAttribute

setAttribute:
  name: status
  value: in_progress      # supports macros

message (chat)

message:
  to: "#channel" | "${owner}" | "<user-key>"
  body: "Heads up: ${title}"

email

email:
  to: "${initiator}"
  cc: "ops@example.com"
  bcc: ""
  from: ""              # optional override
  replyTo: ""           # optional
  subject: "Resolved: ${title}"
  body: ${conclusion}
  log: true             # optional, log the email send
  logBody: true         # optional, log the body too

script

script: route-by-category

route-by-category must match a name: under top-level scripts:. See Scripting (Starlark).

agent

agent: triage

triage must match a name: under top-level agents:, or an org-level agent. It answers in the mode it has in the app’s channel, which the app does not set. See Agents in YAML.

Per-attribute triggers

Attributes can carry a single trigger: that fires when that attribute changes. Equivalent to an onEdit trigger with attribute: matching, but co-located with the attribute definition.

- name: status
  type: select
  trigger:
    setAttribute:
      name: conclusion
      value: "Status: ${status.label}"

Each Option can also carry a trigger that fires when that option is selected:

- name: status
  type: select
  options:
    - name: resolved
      label: Resolved
      state: closed
      trigger:
        conclude: true

Loop protection

Scripts and agents only fire on user-originated events. A trigger that runs a script and the script posts a comment will not re-trigger itself — the post carries a marker that blocks onComment from dispatching scripts/agents on that comment.

Declarative cascades (setAttribute, message, email, alert) still chain, up to 8 levels deep. After that, the cascade stops.

Implication: if you want a script that re-fires on itself (e.g. a periodic animation), use conclude.schedule() — see Scripting (Starlark).

Trigger dispatch order

When an event fires triggers:

1. Script triggers dispatch sequentially via the notification queue.
2. Agent triggers dispatch concurrently (each runs on its own).
3. conclude and setAttribute actions are collected from all triggers, then applied to the activity as a single change.
4. message / email actions fire asynchronously.
5. alert channels are added to the notification’s alert list.

Steps 1 and 2 skip events that a trigger caused.

Multiple triggers on the same event run in YAML order.

Trigger resolution by event