Triggering Notifications

The notify attribute allows you to trigger build notifications to different services. You can also choose to conditionally send notifications based on pipeline events like build state.

Add notifications to your pipeline with the notify attribute. This sits at the same level as steps in your pipeline YAML.

For example, to send a notification email every time a build is created:

pipeline.yml
steps:
  - command: "tests.sh"

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

Available notification types:

  • Email: Send an email to the specified email address.
  • Basecamp: Post a message to a Basecamp Campfire. Requires a Basecamp Chatbot to be configured in your Basecamp organization.
  • Slack: Post a message to the specified Slack Channel. Requires a Slack notification service to be enabled for each channel.
  • Webhooks: Send a notification to the specified webhook URL.
  • PagerDuty

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:

pipeline.yml
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.

To trigger conditional notifications to a Slack channel, you will first need to configure Conditional notifications for Slack.

Email

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

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

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

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:

pipeline.yml
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.

Campfire messages can only be sent using Basecamp 3.

  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:
pipeline.yml
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 a Slack integration for the channel or user that you want to post to. Buildkite customers on the Enterprise plan can also check the 'Manage Notifications Services' checkbox to create, edit, or delete notification services. For detailed information about setting up a Notification Service, see the Slack integration page.

Once a Slack channel has been configured in your organization, add a Slack notification to your pipeline using the slack attribute of the notify YAML block. Remember that if you rename or modify the Slack channel for which the integration was set up, for example if you change it from public to private, you need to set up a new integration.

When using just a channel name, you must specify it in quotes, as otherwise the # will cause the channel name to be treated as a comment.

For example, to deliver build-level notifications to the #general channel of all configured workspaces:

pipeline.yml
steps:
  - command: "tests.sh"

notify:
  - slack: "#general"

For step-level notifications to the #general channel of all configured workspaces, use the following syntax:

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

For example, to deliver build-level notifications to user @someuser in all configured workspaces:

pipeline.yml
notify:
  - slack: "@someuser"

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

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

To send a notification to one particular workspace and channel or workspace and user, specify the workspace name, too:

Build-level notifications for channels

pipeline.yml
steps:
  - command: "tests.sh"

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

Step-level notifications for channels

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

You can also specify multiple teams and channels with the channels attribute:

Build-level notifications

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

Step-level notifications

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

To add a custom message to the notification:

Build-level notifications

pipeline.yml
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

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

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

pipeline.yml
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:

pipeline.yml
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:

pipeline.yml
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:

pipeline.yml
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:

pipeline.yml
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:

pipeline.yml
steps:
  - command: "tests.sh"

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

Build states

Build state can be one of 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.

When a triggered build fails, the step that triggered it will be stuck in the running state forever.

When all the steps in a build are skipped (either by using skip attribute or by using `if` condition), the build state will be marked as `not_run`.

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

Job states

Job state can be one of pending, waiting, waiting_failed, blocked, blocked_failed, unblocked, unblocked_failed, limiting, limited, scheduled, assigned, accepted, running, finished, canceling, canceled, timing_out, timed_out, skipped, or broken.

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