Triggering notifications

Conditional notifications

To only trigger notifications under certain conditions, add the if attribute.

For example, the following email notification will only be triggered if the build passes:

steps:
  - command: "tests.sh"

notify:
  - email: "dev@acmeinc.com"
    if: build.state == "passed"

See Supported variables for more conditional variables that can be used in the if attribute.

Email

Add an email notification to your pipeline using the email attribute of the notify YAML block:

notify:
  - email: "dev@acmeinc.com"

You can only send email notifications on entire pipeline events, specifically upon build.failing and build.finished.

Restrict notifications to finished builds by adding a conditional:

notify:
  - email: "dev@acmeinc.com"
    if: build.state != "failing"

The email attribute accepts a single email address as a string. To send notifications to more than one address, add each address as a separate email notification attribute:

steps:
  - command: "tests.sh"

notify:
  - email: "dev@acmeinc.com"
  - email: "sre@acmeinc.com"
  - email: "qa@acmeinc.com"

Basecamp Campfire message

To send notifications to a Basecamp Campfire, you'll need to set up a chatbot in Basecamp as well as adding the notification to your pipeline.yml file. Basecamp admin permission is required to setup your chatbot.

1. Add a chatbot to the Basecamp project or team that you'll be sending notifications to.
2. Set up your chatbot with a name and an optional URL. If you'd like to include an image, you can find the Buildkite logo in our Brand assets.
3. On the next page of the chatbot setup, copy the URL that Basecamp provides in the curl code snippet
4. Add a Basecamp notification to your pipeline using the basecamp_campfire attribute of the notify YAML block and the URL copied from your Basecamp chatbot:

steps:
  - command: "tests.sh"

notify:
  - basecamp_campfire: "https://3.basecamp.com/1234567/integrations/qwertyuiop/buckets/1234567/chats/1234567/lines"

The basecamp_campfire attribute accepts a single URL as a string.

Basecamp notifications happen at the following events, unless you restrict them using conditionals:

• build created
• build started
• build blocked
• build finished
• build skipped

Slack channel and direct messages

You can set notifications:

• On build status events in the Buildkite UI, by using your Slack Notification Service's 'Build State Filtering' settings.
• On step status and other non-build events, by extending the Slack Notification Service using the notify attribute in your pipeline.yml.

Before adding a notify attribute to your pipeline.yml, ensure an organization admin has set up either a Slack Workspace for a single authorization, or individual notification services for the channel or user that you want to post to. Buildkite customers on the Enterprise plan and using individual notification services can also check the 'Manage Notifications Services' checkbox to create, edit, or delete notification services. For detailed information about setting up a Workspace, see the Slack Workspace Integration page and Slack integration page for configuring individual notification services.

Once a Slack channel or workspace has been configured in your organization, add a Slack notification to your pipeline using the slack attribute of the notify YAML block.

Notify a channel in all workspaces

You can notify a channel in all workspaces by providing the channel name in the pipeline.yml.

Build-level notifications to the #general channel of all configured workspaces:

steps:
  - command: "tests.sh"

notify:
  - slack: "#general"

Step-level notifications to the #general channel of all configured workspaces:

steps:
  - label: "Example Test - pass"
    command: echo "Hello!"
    notify:
      - slack: "#general"

Notify a user in all workspaces

You can notify a user in all workspaces by providing their username in the pipeline.yml.

Build-level notifications to user @someuser in all configured workspaces:

notify:
  - slack: "@someuser"

Step-level notifications to user @someuser in all configured workspaces:

steps:
  - label: "Example Test - pass"
    command: echo "Hello!"
    notify:
      - slack: "@someuser"

Notify a channel in one workspace

You can notify one particular workspace and channel or workspace and user by specifying the workspace name.

Build-level notifications:

steps:
  - command: "tests.sh"

notify:
  # Notify channel
  - slack: "buildkite-community#general"
  # Notify user
  - slack: "buildkite-community@someuser"

Step-level notifications:

steps:
  - label: "Example Test - pass"
    command: echo "Hello!"
    notify:
      # Notify channel
      - slack: "buildkite-community#general"
      # Notify user
      - slack: "buildkite-community@someuser"

Notify multiple teams and channels

You can specify multiple teams and channels by listing them in the channels attribute.

Build-level notifications:

notify:
  - slack:
      channels:
        - "buildkite-community#sre"
        - "buildkite-community#announcements"
        - "buildkite-team#monitoring"
        - "#general"

Step-level notifications:

steps:
  - label: "Example Test - pass"
    command: echo "Hello!"
    notify:
      - slack:
          channels:
            - "buildkite-community#sre"
            - "buildkite-community#announcements"
            - "buildkite-team#monitoring"
            - "#general"

Notify only on first failure

You can filter build notifications to only trigger on the first failure using started_failing.

Build-level notifications:

notify:
  - slack: "#builds"
    if: build.branch == "main" && pipeline.started_failing

Custom messages

You can define a custom message to send in the notification using the message attribute.

Build-level notifications:

notify:
  - slack:
      channels:
        - "buildkite-community#sre"
      message: "SRE related information here..."
  - slack:
      channels:
        - "buildkite-community#announcements"
      message: "General announcement for the team here..."

Step-level notifications:

steps:
  - label: "Example Test - pass"
    command: echo "Hello!"
    notify:
      - slack:
          channels:
            - "buildkite-community#sre"
          message: "SRE related information here..."
      - slack:
          channels:
            - "buildkite-community#announcements"
          message: "General announcement for the team here..."

Custom messages with user mentions

To mention a specific user in a custom message within a notification, use the <@user-id> annotation, substituting userid with the Slack user ID of the person to mention. See the Slack documentation on mentioning users for more details, including how to find a particular user's user ID. You can even mention user groups using the <!subteam^$subteam-id> annotation (where the first subteam is literal text)! See the Slack documentation on mentioning user groups for more information.

Build-level notifications:

notify:
  - slack:
      channels:
        - "#general"
      message: "This message will ping the user with ID U024BE7LH <@U024BE7LH>!"

Step-level notifications:

steps:
  - label: "Slack mention"
    command: echo "Sending a notification with a mention"
    notify:
      - slack:
          channels:
            - "#general"
          message: "This message will ping the group with ID SAZ94GDB8 <!subteam^SAZ94GDB8>!"

Conditional Slack notifications

You can also add conditionals to restrict the events on which notifications are sent:

notify:
  - slack: "#general"
    if: build.state == "passed"

See Supported variables for more conditional variables that can be used in the if attribute.

Slack notifications happen at the following event:

• build finished

An example to deliver slack notification when a step is soft-failed:

steps:
  - command: exit -1
    soft_fail: true
    key: 'step1'
  - wait: ~
  - command: |
      if [ $(buildkite-agent step get "outcome" --step "step1") == "soft_failed" ]; then
         cat <<- YAML | buildkite-agent pipeline upload 
         steps:
           - label: "Notify slack about soft failed step"
             command: echo "Notifying slack about the soft_failed step"
             notify:
               - slack:
                   channels:
                     - "#general"
                   message: "Step1 has soft failed."
      YAML
      fi

Webhooks

Send a notification to a webhook URL from your pipeline using the webhook attribute of the notify YAML block:

steps:
  - command: "tests.sh"

notify:
  - webhook: "https://webhook.site/32raf257-168b-5aca-9067-3b410g78c23a"

The webhook attribute accepts a single webhook URL as a string. To send notifications to more than one endpoint, add each URL as a separate webhook attribute:

steps:
  - command: "tests.sh"

notify:
  - webhook: "https://webhook.site/82n740x6-168b-5aca-9067-3b410g78c23a"
  - webhook: "https://webhook.site/32raf257-81b6-9067-5aca-78s09m6102b4"
  - webhook: "https://webhook.site/27f518bw-9067-5aca-b681-102c847j917z"

Webhook notifications happen at the following events, unless you restrict them using conditionals:

• build created
• build started
• build blocked
• build finished

PagerDuty change events

If you've set up a PagerDuty integration you can send change events from your pipeline using the pagerduty_change_event attribute of the notify YAML block:

steps:
  - command: "tests.sh"

notify:
  - pagerduty_change_event: "636d22Yourc0418Key3b49eee3e8"

Email notifications happen at the following event:

• build finished

Restrict notifications to passed builds by adding a conditional:

steps:
  - command: "tests.sh"

notify:
  - pagerduty_change_event: "636d22Yourc0418Key3b49eee3e8"
    if: "build.state == 'passed'"

Build states

A build state can be one of of the following values:

creating, scheduled, running, passed, failing, failed, blocked, canceling, canceled, skipped, not_run.

You can query for finished builds to return builds in any of the following states: passed, failed, blocked, or canceled.

See the full build states diagram for more information on how builds transition between states.

Job states

A job state can be one of the following values:

pending, waiting, waiting_failed, blocked, blocked_failed, unblocked, unblocked_failed, limiting, limited, scheduled, assigned, accepted, running, finished, canceling, canceled, expired, timing_out, timed_out, skipped, or broken.

See the full job states diagram for more information on how jobs transition between states.