How to Integrate CircleCI with Slack
Get CircleCI alerts directly in your Slack workspace
Teams can be notified of a CircleCI pipeline successes and failures directly in Slack, to streamline reporting and any required actions. In this tutorial, we’ll guide you through a step-by-step process of integrating slack with your CircleCI projects.
What you'll need
To follow along with this tutorial, you’ll need the following.
- Access to a Slack workspace you can add apps to
- Access to a CircleCI account with at least one pipeline already set up.
Create and Install a New Slack App
The first step in integrating CircleCI with Slack is to create a new Slack app. This might sound a little intimidating, but don’t worry, it’s as simple as clicking a few links and buttons, as we’ll see.
Visit api.slack.com/apps, and sign in if you’re not already signed in to your workspace.
Click Create New App and select From scratch from the modal that appears.
Give the app a name and choose the Slack workspace you want to link the app with. Here’s an imaginative name idea: “CircleCI”.
Click Create App.
The next step is to choose what the app can do. Select Permissions under the Add features and functionality section.
On the OAuth & Permissions page, in the Scopes section under Bot Token Scopes, click Add an OAuth Scope, and select, chat:write from the menu.
Add another scope by selecting chat:write.public. These two permissions ensure that our app will be able to send messages to both public and private channels it’s invited to.
Go to the top of the same OAuth & Permissions page and click on the Install to Workspace button.
Slack will ask whether you want to grant permissions to the newly created app. Click Allow.
You’ll be redirected back to the Permissions page. Copy the Bot User OAuth Token from that page, and save it somewhere.
Adding Environment Variables to CircleCI
CircleCI uses an orb under the hood to implement the functionality of sending Slack messages. This orb needs access to a couple of environment variables to be able to do that. Let’s set up these environment variables next.
Go to your CircleCI project page and click Project Settings at the top right of the page.
On the project settings page, select Environment Variables from the sidebar menu.
Give the variable the name “SLACK_ACCESS_TOKEN” and paste in the OAuth token you copied in the previous section as the value.
Add another variable called “SLACK_DEFAULT_CHANNEL”, its value being the ID of the Slack channel you want to set as default for CircleCI notifications. The default channel is the one that gets chosen if you don’t explicitly provide a channel when setting up the CircleCI orb.
You can access the ID of a slack channel by right-clicking on the channel and selecting Copy link. The last part of the URL is the ID.
If you want to limit these environment variables only to selected orbs, you can scope them to a Context and then specify that context in the Slack Orbs you create for each project.
Adding the Notify Step to a CI Job
To complete this integration, we’ll need to set up an orb that will send customized notifications to Slack with any project updates. As an example, we’ll create an orb that notifies us when a build fails. We’re using a node.js project as an example, but you can customize the orb according to your own stack.
.circleci/config.yml file, make sure you’re using version 2.1 of CircleCI.
Add the following orbs stanza right after the version declaration:
orbs: node: 'circleci/node:4.1' slack: email@example.com
Add the following configuration
jobs: build: executor: name: node/default steps: - checkout - node/install-packages - run: command: npm run build - slack/notify: channel: <your_channel_id> event: fail template: basic_fail_1 workflows: build-workflow: jobs: - build
Note that we’re using a pre-built template called
basic_fail_1 as our message template. If you want to use a custom message instead, see the docs here.
Now whenever this CircleCI job exits with a failure status, you’ll receive a message like the following in Slack.
A failure-to-build event is only one of a number of events you want to be notified about. You can follow a similar pattern and explore CircleCI’s documentation to add more events to be notified about.
Allma– UI-less Incident Collaboration. Natively in Slack.