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:
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 Workspace or individual Slack notification services to be enabled for each channel.
- Webhooks: Send a notification to the specified webhook URL.
- PagerDuty
These types of notifications are available at the following levels.
Build | Step |
---|---|
Slack | Slack |
Basecamp | |
Webhook | |
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:
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.
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.
Campfire messages can only be sent using Basecamp 3.
- Add a chatbot to the Basecamp project or team that you'll be sending notifications to.
- 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.
- On the next page of the chatbot setup, copy the URL that Basecamp provides in the
curl
code snippet - Add a Basecamp notification to your pipeline using the
basecamp_campfire
attribute of thenotify
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 step status and other non-build events, by extending your Slack or Slack Workspace notification service with the
notify
attribute in yourpipeline.yml
. - On build status events in the Buildkite interface, by using your Slack notification service's Build state filtering settings.
Before adding a notify
attribute to your pipeline.yml
, ensure a Buildkite organization admin has set up either the Slack Workspace notification service (a once-off configuration for each workspace), or the required Slack notification services, to send notifications to a channel or a user. Buildkite customers on the Enterprise plan can also select the Manage Notifications Services checkbox to allow their users to create, edit, or delete notification services.
The Slack Workspace notification service requires a once-off configuration (only one per Slack workspace) in Buildkite, and then allows you to notify specific Slack channels or users, or both, directly within relevant pipeline steps.
The Slack notification service requires you to first configure one or more of these services for a channel or user, along with the pipelines, branches and build states that these channels or users receive notifications for. Once configured, your pipelines will generate automated notifications whenever the conditions in these notification services are met. You can also use the
notify
attribute in yourpipeline.yml
file for more fine grained control, by mentioning specific channels and users in these attributes, as long as Slack notification services have been created for these channels and users. If you mention any channels or users in a pipelinenotify
attribute for whom a Slack notification service has not yet been configured, the notification will not be sent. For a simplified configuration experience, use the Slack Workspace notification service instead.
Learn more about these different Slack Workspace and Slack notification services within Other integrations.
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.
When using only a channel name, you must specify this name in quotes. Otherwise, the #
will cause the channel name to be treated as a comment.
If you have a Slack notification service configured for a given Slack channel and you either rename this channel, or change the channel's visibility from public to private, then you will need to set up a new Slack notification service to accommodate this modification. This issue does not affect the Slack Workspace notification service, since only one service needs to be configured for a given Slack workspace.
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"
Step-level vs build-level notifications
A step-level notify step will ignore the requirements of a build-level notification. If a build-level notification condition is that it runs only on main
, a step-level notification without branch conditionals will run on all branches.
Notify a user in all workspaces
You can notify a user in all workspaces configured through your Slack or Slack Workspace notification services by providing their username or user ID, respectively, in the pipeline.yml
.
Unlike Slack notification service notifications, which are sent directly to the user's Slack account, the Slack Workspace notification service sends notifications to the user's Buildkite Builds app in Slack.
Build-level notifications
When using Slack notification services, specify the user's handle (for example, @someuser
) to notify this user about a build. The user will receive a notification in all Slack workspaces they have been configured for with this service type. For example:
notify:
- slack: "@someuser"
or:
notify:
- slack:
channels: ["@someuser"]
or:
notify:
- slack:
channels:
- "@someuser"
When using the Slack Workspace notification service, specify the user's user ID (for example, U12AB3C456D
) instead of their user handle (@someuser
), to notify this user about a build in the configured Slack workspace. For example:
notify:
- slack: "U12AB3C456D"
or:
notify:
- slack:
channels: ["U12AB3C456D"]
or:
notify:
- slack:
channels:
- "U12AB3C456D"
Step-level notifications
When using the Slack notification services, specify the user's handle (for example, @someuser
) to notify this user about this step's job. The user will receive a notification in all Slack workspaces they have been configured for with this service type. For example:
steps:
- label: "Example Test - pass"
command: echo "Hello!"
notify:
- slack: "@someuser"
When using the Slack Workspace notification service, specify the user's user ID (for example, U12AB3C456D
) instead of their user handle (@someuser
), to notify this user about this step's job in the configured Slack workspace. For example:
steps:
- label: "Example Test - pass"
command: echo "Hello!"
notify:
- slack: "U12AB3C456D"
Notify a channel in one workspace
You can notify one particular workspace and channel by specifying the workspace name.
Build-level notifications:
steps:
- command: "tests.sh"
notify:
# Notify channel
- slack: "buildkite-community#general"
Step-level notifications:
steps:
- label: "Example Test - pass"
command: echo "Hello!"
notify:
# Notify channel
- slack: "buildkite-community#general"
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"
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..."
You can also send notifications with custom messages to specific users with the relevant syntax mentioned in Notify a user in all workspaces. Employ the appropriate user notification syntax based on your configured the Slack or Slack Workspace notification service/s.
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>!"
Build creator environment variable
You cannot substitute user
with the build creator environment variable value.
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.
You are able to use pipeline.started_passing
and pipeline.started_failing
in your if statements if you are using the Slack Workspace integration.
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
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
Notify only on first pass
You can filter build notifications to only trigger on the first pass after a previous failed build using started_passing
. pipeline.started_passing
is the successor to build.fixed
, which is deprecated, but remains available to use for backwards compatibility.
Build-level notifications:
notify:
- slack: "#builds"
if: build.branch == "main" && pipeline.started_passing
Notify on all failures and first successful pass
You can filter build notifications to only trigger when a pipeline:
- Starts failing
- Continues to fail
- Starts passing after a failure
Build-level notifications:
notify:
- slack: "#builds"
if: build.state == failed || pipeline.started_passing
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
.
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
.
Unlike the notify
attribute, the build state value for a steps
attribute may differ depending on the state of a pipeline. For example, when a build is blocked within a steps
section, the state
value in the API response for getting a build retains its last value (for example, passed
), rather than having the value blocked
, and instead, the response also returns a blocked
field with a value of true
.
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.