--- title: "Use the Slack orb to set up notifications" description: "Get started with the CircleCI Slack orb: create your config.yml file, connect CircleCI with Slack, and use message templates for notifications." platform: "Cloud, Server" doc_version: "Server" last_updated: "2026-10-23" --- > For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md). > > For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt). # Use the Slack orb to set up notifications This guide gets you started with the CircleCI Slack orb. ## Introduction Orbs are shareable packages of reusable configuration elements. They help you reduce complexity, integrate your software with third-party apps, and save time. One of CircleCI’s most popular orbs is the Slack orb. The Slack orb allows you to implement event-based notifications across all your CI/CD pipelines. Using either built-in message templates or Slack’s visual Block Kit Builder, you can create and customize notifications specific to your organization’s needs. In this tutorial, you will learn how to: * Create a `config.yml` file using the Slack orb. * Store your Slack credentials securely in a context. * Use templates to create alerts for successful and failed builds. * Alert specific channels, teams, or people. * Access the Slack Block Kit Builder to create your own customized alerts. To follow this tutorial, you need: * An account on your CircleCI Server instance connected to GitHub. * A [Slack workspace](https://slack.com) (you can create your own for testing purposes, if you do not want to use your company workspace). * A project you are following in CircleCI for which you want to integrate Slack notifications. ## 1\. Create your config.yml file If you have not already done so, create a `.circleci` folder at the root of your repo. Inside the `.circleci` folder, create a `config.yml` file. The sample code below shows the basics you need to set up Slack notifications in your `config.yml` file. You can copy and paste the whole thing or take the individual elements and incorporate them into your project `config.yml` file: ```yaml version: 2.1 orbs: slack: circleci/slack@4.9.3 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 ``` The following commentary describes what occurs in the main elements of the sample code: * **Line 1:** This indicates the config version you are using. `2.1` is the most recent version. * **Lines 2-3:** This is the orbs stanza. You are using the `slack: circleci/slack@4.9.3` orb. * **Lines 5-7:** This is a job called `notify`, which is executed in a basic Docker container. * **Lines 8-9:** This is a step which must be called `slack/notify` to work with the Slack orb. * **Lines 10-24:** This custom block includes a basic notification from the Slack Block Kit Builder. As you can see, it is in JSON format. In Part 3, you will use more sophisticated templates. * **Line 25:** The `event: always` parameter means this notification is triggered for _all_ event types. In Part 3, you will use different notifications for different events. Now you have a basic `config.yml` file set up, you can connect CircleCI with Slack. If you commit your `config.yml` file at this point and trigger a pipeline, your build will fail. You need to add your Slack credentials in the next step. ## 2\. Connect CircleCI with Slack In this step, you will: * Obtain an API token from Slack. * Create a context to store those credentials in CircleCI. * Trigger the pipeline so you receive a notification. ### a. Authenticate your application The Slack orb is an application that executes as part of your job on CircleCI. Before you can receive notifications, you need to authenticate your application. #### i. Create a Slack app 1. Visit [**Your Apps** on the Slack API website](https://api.slack.com/apps) and select the green **Create an App** button. 2. Choose **From scratch**. 3. Give your app a name, for example, `CircleCI`, and select the Slack workspace in which you want to use it. You cannot change this workspace afterwards. 4. Select the green **Create App** button. #### ii. Set your app permissions 1. On the Basic Information page, locate the **Permissions** tile under _Add features and functionality_. 2. On the _OAuth & Permissions_ page, scroll down to **Scopes**. Create the permissions for your Slack app here. 3. Under **Bot Token Scopes**, select **Add an OAuth Scope**. 4. The Slack orb needs permission to post chat messages and upload files, so create the following scopes: * chat:write * chat:write.public * files:write To receive Slack notifications in a private channel, you need to add your Slack app to that channel. Open the channel, select the photos of the channel members in the top right-hand corner, then select the **Integrations** tab. From here, you can add an app. #### iii. Install your app 1. Once you have created your scopes, scroll up to the top of the page and select the **Install to Workspace** button. 2. You will then be asked to grant permission for the app to access your Slack workspace. Select the disclosure triangle to double-check the permissions, then select the green **Allow** button. 3. You see a **Bot User OAuth Token**. Copy this token to your clipboard, ready to add it to CircleCI. Make sure you keep this private. ### b. Create a context In CircleCI, contexts allow you to secure and share environment variables across projects. Once you have created a context with your Slack credentials, you and your colleagues will be able to reuse them. In CircleCI: 1. Select the **Org** page. > **Image:** Org Figure 1. Guides:Root:Slack Orb Organization Settings 2. Under Context, select the blue **Create Context** button and add a unique name, such as `slack-secrets` (that is the name specified in the `config.yml` file above). > **Image:** Create Context Figure 2. Guides:Root:Slack Orb Create Context 3. Select the blue **Create Context** button. 4. Select the name of the context you just created. 5. Select the blue **Add Environment Variable** button and enter your first key value pair. * The Environment Variable Name is `SLACK_ACCESS_TOKEN`. * The value is your Slack Bot User OAuth Access Token. > **Image:** Add Environment Variable Figure 3. Guides:Root:Slack Orb Environment Variable 6. Select the **Add Environment Variable** button to save it. 7. Select the blue **Add Environment Variable** button again. * The Environment Variable Name is `SLACK_DEFAULT_CHANNEL`. * The value is the ID of the default Slack channel for posting your notifications. You can override this setting in your individual jobs. To get the ID for your Slack channel, right-click the channel in Slack and choose **Copy Link**. The ID will be visible at the end of the URL and will be in this format: C034R26AM36. 8. Include the `slack-secrets` context in your `notify` job as follows: ```yaml workflows: send-notification: jobs: - notify: context: slack-secrets ``` You can reuse this context in other jobs and projects. ### c. Trigger an alert 1. Commit your `config.yml` file (and push it, if you are working remotely). This triggers your CircleCI pipeline, which uses the Slack orb with your credentials. You will then see a green **Success** badge and a green tick next to your `notify` job. > **Image:** Success Figure 4. Guides:Root:Slack Orb Success 2. Select your job to see what just happened. You see the message body that was sent to Slack. 3. Now open your Slack workspace. In the default channel you specified earlier, you see the alert triggered by your CircleCI pipeline. Although this is a basic alert, you have achieved a lot already: * Created a `.circleci/config.yml` file with the Slack orb. * Created a context to store your Slack-related environment variables. * Created a Slack app. ## 3\. Use message templates The Slack orb includes several notification templates you can use to notify your channel of various CircleCI events: * `basic_success_1` - for _pass_ events where the job succeeded. * `basic_fail_1` - for _fail_ events, where the job failed. * `success_tagged_deploy_1` - for successful deployments. * `basic_on_hold_1` - for on-hold jobs that are awaiting approval. To use these templates in your job, include the `event` and `template` parameters under `steps` in the `config.yml` file. For example: ```yaml jobs: notify: docker: - image: cimg/base:current steps: - slack/notify: event: fail template: basic_fail_1 - slack/notify: event: pass template: success_tagged_deploy_1 ``` * **Line 7** specifies that the template on the next line is used for failed events. * **Line 8** specifies the template to be used, in this case `basic_fail_1`. * **Line 9** specifies that the template on the next line is used for pass events. * **Line 10** specifies the template to be used, in this case `success_tagged_deploy_1`. Whereas in Step 1 you used an all-purpose alert, now you have included different steps according to whether the job has passed or failed. The Slack orb triggers the appropriate step. Commit your updated `config.yml` file (and push it, if you are working remotely). Once the pipeline is complete, you see a more sophisticated alert in your Slack channel. ### a. Including additional parameters You can also include a mention for a failed job, to alert a specific person or team: ```yaml - slack/notify: event: fail mentions: '@EngineeringTeam' template: basic_fail_1 ``` To notify multiple channels, place the IDs in quotes and separate them with a comma: ```yaml - slack/notify: channel: 'ABCXYZ, ZXCBN' event: fail template: basic_fail_1 ``` To restrict your alert to a specific branch, add a `branch_pattern` parameter: ```yaml - slack/notify: branch_pattern: main event: fail template: basic_fail_1 ``` Restricting your alert to a specific branch is useful if, for example, you do not want to receive alerts for feature branches. ### b. Use the Slack Block Kit Builder If you would like to further customize your notifications, you can use the [Slack Block Kit Builder](https://api.slack.com/block-kit/building). This framework allows you to create sophisticated notifications, using images, form fields, and other interactive elements. Once you have created your block (which is a JSON object), copy and paste it into your `config.yml` file within the `custom` parameter: ```yaml - slack/notify: event: always custom: | # your custom notification goes here { "blocks": [ { "type": "section", "fields": [ { "type": "plain_text", "text": "*This is a text notification*", "emoji": true } ] } ] } ``` ## Conclusion In this tutorial, you have configured the Slack orb to send CircleCI notifications to your Slack channel. You created a basic notification, built and authenticated your Slack app, and used templates. For further configuration options, take a look at the [Slack orb documentation](https://circleci.com/developer/orbs/orb/circleci/slack). You can also find many more orbs in the [Orb Registry](https://circleci.com/developer/orbs).