Customers often need to send custom slack or email notifications when steps fail. If an important build or deploy step fails, then someone needs to know about it. But, this hasn't been the simplest process until now.

You can now reference a step's information (id, key, label, type, state and outcome) in conditionals by prefixing with step. (such as step.id). This is particularly useful when you need to notify someone as soon as a step fails. See detailed descriptions of these values in our docs on conditional variables.

Here's how simple it is now:

1
2
3
4
5
6
7
8
steps:
  - command: false
    notify:
      - slack:
          channels: ["#engineering"]
          if: step.outcome == "hard_failed"
          message: "Important step failed, please fix."
  - command: sleep 1000

Previously, the recommended solution required conditionally uploading a new step to handle notifications:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
steps:
  - label: "Fail"
    command: exit 1
    key: "fail"
  - label: "Run regression only if fail check is failed"
    depends_on: "fail"
    command: |
      if [ $$(buildkite-agent step get "outcome" --step "fail") == "hard_failed" ]; then
         cat <<- YAML | buildkite-agent pipeline upload
         steps:
           - label: notify"
             command: notification.sh
      YAML
      fi

For quick reference, options for step.outcome are neutral, passed, errored, hard_failed or soft_failed. step.state can be one of ignored, waiting_for_dependencies, ready, running, failing or finished. step.type exposes the step's type such as command or trigger. Step key and label are user defined values.

This new syntax works with all notification types (Slack, email, webhooks, etc.) and can be combined with other conditions using standard operators (&&, ||). Each step's notification can only reference its own outcome - you can't reference other steps' outcomes directly in the notification conditional.

Notifications are sent immediately when the step completes with the specified outcome, providing faster feedback when issues occur.