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.

The below example will send a notification email every time a build is created on this pipeline:

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

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

Available notification types:

<!-- vale off --> <!-- vale on -->
email Send an email to the specified email address.
Required attributes: email
basecamp Post a message to a Basecamp Campfire. Requires a Basecamp Chatbot to be configured in your Basecamp organization.
Required attributes: basecamp_campfire
slack Post a message to the specified Slack Channel. Requires a Slack notification service to be enabled for each channel.
Required attributes: slack
webhooks Send a notification to the specified webhook URL.
Required attributes: webhook

Further details for each attribute can be found in the corresponding sections below.

Conditional notifications

You can choose to only trigger notifications when a statement evaluates to true using the if attribute.

In the below example the email notification will only be triggered if the build passes:

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

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"

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
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 will be 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
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.

Slack Channel and Direct Messages

If you need fine-grained control over your notifications, or want to send notifications triggered by non-build events, the Slack Notification Service can be extended using the notify attribute.

If you only need to send notifications on build status events, you can set this up in Buildkite using your Slack Notification Service's 'Build State Filtering' settings.

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

For channels:

pipeline.yml
notify:
  - slack: "#general"

For users:

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

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.

The above example will deliver the notification to all configured workspaces that have a channel named 'general'.

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

For channels

pipeline.yml
notify:
  - slack: "buildkite-community#general"

For users:

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

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

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

In the example above, the notification will be sent to the 'sre' and 'announcements' channels in the 'buildkite-community' workspace, the 'monitoring' channel in the 'buildkite-team' workspace, as well as to the 'general' channel of all configured workspaces.

You can add a custom message to the notification:

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..."

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

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

Webhooks

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

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