> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/slack

Implement event-based notifications across all of your CI/CD pipelines. Utilizing built-in message templates or Slack's visual Block-Kit builder, create and customize notifications specific to your organization's needs. Supports Linux x86_64, MacOS, Arm64 V8, and Windows.


## Commands

### notify

Notify a Slack channel with a custom message.
The environment variables SLACK_ACCESS_TOKEN and SLACK_DEFAULT_CHANNEL must be set for this orb to work.
For instructions on how to set them, follow the setup guide available in the wiki: https://github.com/CircleCI-Public/slack-orb/wiki/Setup.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api_domain` | string | slack.com | Domain for the Slack API. Use slack.com for regular Slack and slack-gov.com for GovSlack.
 |
| `branch_pattern` | string |  | A comma separated list of regex matchable branch names. Notifications will only be sent if sent from a job from these branches. Pattern must match the full string, no partial matches.
 |
| `channel` | string | $SLACK_DEFAULT_CHANNEL | Select which channel in which to post to. Channel name or ID will work. You may include a comma separated list of channels if you wish to post to multiple channels at once. Set the "SLACK_DEFAULT_CHANNEL" environment variable for the default channel.
 |
| `circleci_host` | string | https://circleci.com | A CircleCI Host which used in a message template.
 |
| `custom` | string |  | Enter a custom message template.

1. Create your message template using the Block Kit Builder: https://app.slack.com/block-kit-builder/.
2. Insert any desired environment variables.
3. Paste value here.
 |
| `debug` | boolean | false | Runs scripts in debug mode for bash.
Enable to view full payload being sent to Slack and response being received from the API call.
Redacted content can be viewed by re-running the job with SSH and accessing the log files referenced in the job output.
When run in a persistent build environment such as CircleCI Runner, these debug log files may remain in the system's temporary filesystem indefinitely and accumulate over time.
 |
| `event` | enum | always | In what event should this message send? Options: ["fail", "pass", "always"]
 |
| `ignore_errors` | boolean | true | Ignore errors posting to Slack.
Disable to catch initial setup errors. Re-enable to prevent Slack errors from affecting your pipeline.
 |
| `invert_match` | boolean | false | Invert the branch and tag patterns.
If set to true, notifications will only be sent if sent from a job from branches and tags that do not match the patterns.
 |
| `mentions` | string |  | Exports to the "$SLACK_PARAM_MENTIONS" environment variable for use in templates.
Mention users via the @ symbol: "@USER"
If the username contains a space, the Slack ID must be used with angled brackets: "<@U8XXXXXXX>"
 |
| `retries` | integer | 0 | The amount of retries when posting the message to slack. Defaults to zero. |
| `retry_delay` | integer | 30 | The amount of seconds to wait between retries. Defaults to 30. |
| `scheduled_offset_seconds` | integer | 0 | When set, the notification is a scheduled message.
 |
| `step_name` | string | Slack - Sending Notification | Specify a custom step name for this command, if desired |
| `tag_pattern` | string |  | A comma separated list of regex matchable tag names. Notifications will only be sent if sent from a job from these branches. Pattern must match the full string, no partial matches.
 |
| `template` | string |  | Select which template to use for the notification by its name. The name must be available as an environment variable.
The built-in templates can be found and previewed at: https://github.com/CircleCI-Public/slack-orb/wiki#templates.
Alternatively, you can create and use your own dynamic templates: https://github.com/CircleCI-Public/slack-orb/wiki/Dynamic-Templates.
If left empty and no custom template is provided, the template will be automatically selected based on the job status.
 |
| `thread_id` | string |  | When set, the first `notify` with a given `thread_id` will appear as a regular slack message.
Any subsequent `notify` usage with the same identifier will be posted within the initial message's thread.
`thread_id` should be set to any arbitrary string to help you identify different threads. See examples for more information.
Enabling thread messages with this parameter implies using a very small amount of cacheing: ~200 B
 |
| `unfurl_links` | boolean | true | Attach content preview when the message containing a link. This allows adding context and continuity to conversations.
Link unfurling is the default treatment for links posted in Slack. When a link is spotted, Slack crawls it and provides a preview.
 |
| `unfurl_media` | boolean | true | Attach content preview when the message containing a media link. This allows adding context and continuity to conversations.
Media unfurling is the default treatment for links posted in Slack. When a media link is spotted, Slack crawls it and provides a preview.
 |
| `windows_execution` | boolean | false | When this command is going to be run on windows, set this to true.
 |

### reaction

Add a reaction to an slack message.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `add_react_name` | string |  | The name of the reaction you want to add, e.g. check, hourglass_flowing_sand, x, etc. |
| `api_domain` | string | slack.com | Domain for the Slack API. Use slack.com for regular Slack and slack-gov.com for GovSlack.
 |
| `branch_pattern` | string |  | A comma separated list of regex matchable branch names. Notifications will only be sent if sent from a job from these branches. Pattern must match the full string, no partial matches.
 |
| `channel` | string | $SLACK_DEFAULT_CHANNEL | Select which channel in which to post to. Only Channel ID is supported for now. Set the "SLACK_DEFAULT_CHANNEL" environment variable for the default channel. |
| `debug` | boolean | false | Runs scripts in debug mode for bash (set -x). |
| `event` | enum | always | In what event should this message send? Options: ["fail", "pass", "always"]
 |
| `invert_match` | boolean | false | Invert the branch and tag patterns.
If set to true, notifications will only be sent if sent from a job from branches and tags that do not match the patterns.
 |
| `remove_react_name` | string |  | The name of the reaction you previsously added, e.g. check, hourglass_flowing_sand, x, etc. |
| `step_name` | string | Add or Remove Reaction to Slack message | Specify a custom step name for this command, if desired |
| `tag_pattern` | string |  | A comma separated list of regex matchable tag names. Notifications will only be sent if sent from a job from these branches. Pattern must match the full string, no partial matches.
 |
| `thread_id` | string |  | The thread id where this reaction will be added. |
| `windows_execution` | boolean | false | When this command is going to be run on windows, set this to true.
 |

## Jobs

### on-hold

Insert this job in-line with your standard CircleCI on-hold notification jobs to simulataniously send a Slack notification containing a link to the paused Workflow.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch_pattern` | string | .+ | A comma separated list of regex matchable branch names.
Notifications will only be sent if sent from a job from these branches.
By default ".+" will be used to match all branches. Pattern must be a POSIX expression and match the full string, no partial matches.
 |
| `channel` | string | $SLACK_DEFAULT_CHANNEL | Select which channel in which to post to. Channel name or ID will work. You may include a comma separated list of channels if you wish to post to multiple channels at once. Set the "SLACK_DEFAULT_CHANNEL" environment variable for the default channel.
 |
| `circleci_host` | string | https://circleci.com | CircleCI Host (used as the base for the Workflow URL)
 |
| `custom` | string |  | (optional) Enter a custom message template.

1. Create your message template using the Block Kit Builder: https://app.slack.com/block-kit-builder/.
2. Insert any desired environment variables.
3. Paste value here.
 |
| `debug` | boolean | false | Runs scripts in debug mode for bash.
View payload and response being sent to slack api.
Enable to view full payload being sent to slack and response being received from the API call.
 |
| `invert_match` | boolean | false | Invert the branch and tag patterns.
If set to true, notifications will only be sent if sent from a job from branches and tags that do not match the patterns.
 |
| `mentions` | string |  | Exports to the "$SLACK_PARAM_MENTIONS" environment variable for use in templates.
Mention users via the @ symbol: "@USER"
If the username contains a space, the Slack ID must be used with angled brackets: "<@U8XXXXXXX>"
 |
| `step_name` | string | Slack - Sending Notification | Specify a custom step name for this command, if desired |
| `template` | string | basic_on_hold_1 | (optional) By default this job will send the standard "basic_on_hold_1" template. In order to use a custom template you must also set this value to an empty string. |
| `thread_id` | string |  | When set, the first `notify` with a given `thread_id` will appear as a regular slack message.
Any subsequent `notify` usage with the same identifier will be posted within the initial message's thread.
`thread_id` should be set to any arbitrary string to help you identify different threads. See examples for more information.
Enabling thread messages with this parameter implies using a very small amount of cacheing: ~200 B
 |

## Examples

### custom_notification

Send a custom notification using Slack's Block Kit Builder.
Create the payload code and paste it in your notify command's custom parameter.
Detailed instructions in the GitHub readme.
https://app.slack.com/block-kit-builder


```yaml
version: '2.1'
orbs:
  slack: circleci/slack@5.0
jobs:
  notify:
    docker:
      - image: cimg/base:current
    steps:
      - slack/notify:
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "fields": [
                    {
                      "type": "plain_text",
                      "text": "*This is a text notification*",
                      "emoji": true
                    }
                  ]
                }
              ]
            }
          event: always
workflows:
  send-notification:
    jobs:
      - notify:
          context: slack-secrets
```

### full_deployment_sample

A full test and deploy sample configuration.
Test your app on every commit. On tagged commits, place the workflow on-hold after testing, pending manual approval for deployment.
Receive a Slack notification when the workflow is placed on hold, and a notification whether the deployment fails or deploys successfully.


```yaml
version: '2.1'
orbs:
  slack: circleci/slack@5.0
jobs:
  deploy:
    docker:
      - image: cimg/base:current
    steps:
      - run: echo "deploy my app"
      - slack/notify:
          event: fail
          mentions: '@EngineeringTeam'
          template: basic_fail_1
      - slack/notify:
          event: pass
          template: success_tagged_deploy_1
  test:
    docker:
      - image: cimg/base:current
    steps:
      - run: echo "test my app"
workflows:
  test-and-deploy:
    jobs:
      - test
      - slack/on-hold:
          context: slack-secrets
          filters:
            tags:
              only: /^v.*/
          requires:
            - test
      - pause_workflow:
          filters:
            tags:
              only: /^v.*/
          requires:
            - test
            - slack/on-hold
          type: approval
      - deploy:
          filters:
            tags:
              only: /^v.*/
          requires:
            - pause_workflow
```

### notify_on_fail_with_template

Send a slack notification when a job fails. This example uses a pre-included template. Custom templates can also be used.
The channel parameter can be used to alert a specific Slack channel.
Ensure the "slack/notify" command is the last command in a job to accurately capture the status.


```yaml
version: '2.1'
orbs:
  node: circleci/node:4.1
  slack: circleci/slack@5.0
jobs:
  deploy:
    executor:
      name: node/default
    steps:
      - checkout
      - node/install-packages
      - run:
          command: npm run deploy
      - slack/notify:
          channel: ABCXYZ
          event: fail
          template: basic_fail_1
workflows:
  deploy_and_notify:
    jobs:
      - deploy:
          context: slack-secrets
```

### notify_thread

Send a Slack notification to a channel and use the same message to post replies in a thread.
`thread_id` parameter holds a thread identifier in case there are multiple notifications in the pipeline


```yaml
version: '2.1'
orbs:
  node: circleci/node:4.1
  slack: circleci/slack@5.0
jobs:
  deploy:
    executor:
      name: node/default
    steps:
      - slack/notify:
          channel: engineering
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "fields": [
                    {
                      "type": "plain_text",
                      "text": "*Deployment started.*",
                      "emoji": true
                    }
                  ]
                }
              ]
            }
          event: always
          thread_id: deployment
      - slack/notify:
          channel: engineering
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "fields": [
                    {
                      "type": "plain_text",
                      "text": "*Deployment finished.*",
                      "emoji": true
                    }
                  ]
                }
              ]
            }
          event: always
          thread_id: deployment
  test:
    executor:
      name: node/default
    steps:
      - slack/notify:
          channel: engineering
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "fields": [
                    {
                      "type": "plain_text",
                      "text": "*Tests started.*",
                      "emoji": true
                    }
                  ]
                }
              ]
            }
          event: always
          thread_id: testing
      - slack/notify:
          channel: engineering
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "fields": [
                    {
                      "type": "plain_text",
                      "text": "*Tests finished.*",
                      "emoji": true
                    }
                  ]
                }
              ]
            }
          event: always
          thread_id: testing
workflows:
  deploy_and_notify:
    jobs:
      - deploy
      - test:
          requires:
            - deploy
```

### notify_two_channels

Send a Slack notification to two channels simultaneously.
By default, if no channel parameter is set, the $SLACK_DEFAULT_CHANNEL value will be used (must be set).
A custom channel, or comma-separated list of channels can be supplied via the "channel" parameter.

It is recommended to use the "channel ID" for the value(s).
View the wiki: https://github.com/CircleCI-Public/slack-orb/wiki/How-to-set-Slack-channel


```yaml
version: '2.1'
orbs:
  node: circleci/node:4.1
  slack: circleci/slack@5.0
jobs:
  deploy:
    executor:
      name: node/default
    steps:
      - slack/notify:
          channel: ABCXYZ, ZXCVBN
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "fields": [
                    {
                      "type": "plain_text",
                      "text": "*This is a text notification*",
                      "emoji": true
                    }
                  ]
                }
              ]
            }
          event: always
workflows:
  deploy_and_notify:
    jobs:
      - deploy:
          context: slack-secrets
```

### on_hold_notification

Pause a Workflow for manual approval and send a Slack notification with a link to the Workflow.


```yaml
version: '2.1'
orbs:
  slack: circleci/slack@5.0
workflows:
  on-hold-example:
    jobs:
      - my_test_job
      - slack/on-hold:
          context: slack-secrets
          requires:
            - my_test_job
      - pause_workflow:
          requires:
            - my_test_job
            - slack/on-hold
          type: approval
      - my_deploy_job:
          requires:
            - pause_workflow
```

### only_notify_on_branch

Use the "branch_pattern" parameter to limit notifications to specified branches. Useful when a job is executed on multiple branches but you only wish to be notified on a subset of branches. For example: If your "build" job runs on every branch, but you wish to only be notified when a failure occurs on the "main" branch, your config may look like this.


```yaml
version: '2.1'
orbs:
  slack: circleci/slack@5.0
jobs:
  build:
    machine: true
    steps:
      - run: some build command
      - slack/notify:
          branch_pattern: main
          event: fail
          template: basic_fail_1
      - slack/notify:
          branch_pattern: production
          event: fail
          mentions: <@U8XXXXXXX>, @UserName
          template: basic_fail_1
workflows:
  deploy_and_notify:
    jobs:
      - build:
          context: slack-secrets
      - deploy:
          filters:
            branches:
              only:
                - production
          requires:
            - build
```

### scheduled_scheduled

Send a custom notification using Slack's Block Kit Builder.
Create the payload code and paste it in your notify command's custom parameter.
Detailed instructions in the GitHub readme.
https://app.slack.com/block-kit-builder


```yaml
version: '2.1'
orbs:
  slack: circleci/slack@5.0
jobs:
  scheduled_notify:
    docker:
      - image: cimg/base:current
    steps:
      - slack/notify:
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "fields": [
                    {
                      "type": "plain_text",
                      "text": "*This is a scheduled text notification*",
                      "emoji": true
                    }
                  ]
                }
              ]
            }
          event: always
          scheduled_offset_seconds: 30
workflows:
  send-notification:
    jobs:
      - scheduled_notify:
          context: slack-secrets
```

### successful_tagged_deployment

Use one of our pre-included templates for sending a success notification when a tagged deployment passes.
Enter a Channel ID in the channel parameter to specify which slack channel to ping.
Ensure the "slack/notify" command is the last command in a job to accurately capture the status.


```yaml
version: '2.1'
orbs:
  node: circleci/node:4.1
  slack: circleci/slack@5.0
jobs:
  deploy:
    executor:
      name: node/default
    steps:
      - checkout
      - node/install-packages
      - run:
          command: npm run deploy
      - slack/notify:
          channel: ABCXYZ
          event: pass
          template: success_tagged_deploy_1
workflows:
  deploy_and_notify:
    jobs:
      - deploy:
          context:
            - slack-secrets
```