Send Slack notifications from your CircleCI pipelines even easier with Slack Orb 4.0
Note: New to Slack notifications? We recommend using the native CircleCI Slack integration instead of this orb. It requires no config changes, supports user tagging, and is where we're focusing new feature development.
Share feedback or feature requests here to help us prioritize what's next.
In order to use the Slack Orb on CircleCI you will need to create a Slack App and provide an OAuth token. Find the guide in the wiki: How to setup Slack orb
For full usage guidelines, see the Orb Registry listing.
The Slack Orb comes with a number of included templates to get your started with minimal setup. Feel free to use an included template or create your own.
| Template Preview | Template | Description |
|---|---|---|
| basic_success_1 | Should be used with the "pass" event. | |
| basic_fail_1 | Should be used with the "fail" event. | |
| success_tagged_deploy_1 | To be used in the event of a successful deployment job. see orb usage examples | |
| basic_on_hold_1 | To be used in the on-hold job. see orb usage examples |
- Open the Slack Block Kit Builder: https://app.slack.com/block-kit-builder/
- Design your desired notification message.
- Replace any placeholder values with $ENV environment variable strings.
- Set the resulting code as the value for your
customparameter.
- slack/notify:
event: always
custom: |
{
"blocks": [
{
"type": "section",
"fields": [
{
"type": "plain_text",
"text": "*This is a text notification*",
"emoji": true
}
]
}
]
}- Develop your code to dynamically generate a template
- Write the template to a local temp file
- Add that temp file to your $BASH_ENV
- Use the new env value to pass your template to the
templatevariable (note: don't pass it to the custom parameter)
- run: ./.circleci/bin/build_template 2>&1 | tee my_template.json
- run:
command: |
echo 'export MY_TEMPLATE=$(jq . my_template.json)' >> $BASH_ENV
- slack/notify:
channel: eng-deploys
thread_id: deployment
event: always
template: MY_TEMPLATELimit Slack notifications to particular branches with the "branch_pattern" or "tag_pattern" parameter.
A comma separated list of regex matchable branch or tag names. Notifications will only be sent if sent from a job from these branches/tags. Pattern must match the full string, no partial matches. Keep in mind that "branch_pattern" and "tag_pattern" are mutually exclusive.
See usage examples.
Post replies in threads with a special parameter thread_id. Including this parameter in the notify command reference stores the id of the message in a small portion of bytes in cache. Any subsequent invocation of the command with the same value for thread_id will post a reply to the initial message in a thread. Example:
- slack/notify:
event: always
channel: engineering
thread_id: testing
custom: |
{
"blocks": [
{
"type": "section",
"fields": [
{
"type": "plain_text",
"text": "*Tests started.*",
"emoji": true
}
]
}
]
}
- slack/notify:
event: always
channel: engineering
thread_id: testing
custom: |
{
"blocks": [
{
"type": "section",
"fields": [
{
"type": "plain_text",
"text": "*Tests finished.*",
"emoji": true
}
]
}
]
}Set the scheduled_offset_seconds special parameter to a number of seconds if you want to post a scheduled message. Example:
- slack/notify:
event: always
scheduled_offset_seconds: 30
custom: |
{
"blocks": [
{
"type": "section",
"fields": [
{
"type": "plain_text",
"text": "*This is a text notification*",
"emoji": true
}
]
}
]
}Set the api_domain parameter to specify which Slack API domain to use. Use slack.com for regular Slack workspaces (default) and slack-gov.com for GovSlack workspaces.
- slack/notify:
event: always
api_domain: slack-gov.com
custom: |
{
"blocks": [
{
"type": "section",
"fields": [
{
"type": "plain_text",
"text": "*This is a text notification to GovSlack*",
"emoji": true
}
]
}
]
}View the FAQ in the wiki
We welcome issues to and pull requests against this repository!
For further questions/comments about this or other orbs, visit CircleCI's orbs discussion forum.