Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Use the Slack orb to set up notifications

8 months ago6 min read
Cloud
Server v4.x
Server v3.x
On This Page

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:

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 into your config.yml file. You can copy and paste the whole thing or take the individual elements and incorporate into your project config.yml file:

version: 2.1
orbs:
  slack: circleci/slack@4.9.3
jobs:
  notify:
    docker:
      - image: 'cimg/base:stable'
    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.

  • Line 30: This references a CircleCI context where you will save your Slack credentials in Step 2.

Now you have a basic config.yml file set up, you can connect CircleCI with Slack.

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 and click the green Create an App button.

    Create a Slack app
  2. Choose From scratch.

    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.

    Name your Slack app
  4. Click 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.

    Slack app Permissions
  2. On the OAuth & Permissions page, scroll down to Scopes. This is where you need to create the permissions for your Slack app.

    Add an OAuth Scope
  3. Under Bot Token Scopes, click 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

      Add Bot Token Scopes

iii. Install your app

  1. Once you have created your scopes, scroll up to the top of the page and click the Install to Workspace button.

    Install to Workspace
  2. You will then be asked to grant permission for the app to access your Slack workspace.

    Allow access
  3. Click the disclosure triangle to double-check the permissions, then click the green Allow button.

  4. You should see a Bot User OAuth Token. Copy this token to your clipboard, ready to add it to CircleCI. Make sure you keep this private.

    Copy OAuth Token

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. Click the Organization Settings page.

    Organization Settings
  2. Under Context, click 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).

    Create Context
  3. Click the blue Create Context button.

  4. Click the name of the context you just created.

  5. Click 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.

      Add Environment Variable
  6. Click the Add Environment Variable button to save it.

  7. Click 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.

      Copy Slack channel link
  8. Include the slack-secrets context in your notify job as follows:

    workflows:
      send-notification:
        jobs:
          - notify:
              context: slack-secrets

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 should then see a green Success badge and a green tick next to your notify job.

    Success
  2. Click on your job to see what just happened. You should see the message body that was sent to Slack.

  3. Now open your Slack workspace. In the default channel you specified earlier, you should see the alert triggered by your CircleCI pipeline.

    Slack text notification

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:

jobs:
  notify:
    docker:
      - image: 'cimg/base:stable'
    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 basic_success_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 should see a more sophisticated alert in your Slack channel.

Deployment Successful alert

a. Including additional parameters

You can also include a mention for a failed job, to alert a specific person or team:

- 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:

- slack/notify:
    channel: 'ABCXYZ, ZXCBN'
    event: fail
    template: basic_fail_1

To restrict your alert to a specific branch, add a branch_pattern parameter:

 - slack/notify:
      branch_pattern: main
      event: fail
      template: basic_fail_1

This is useful if 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. 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:

- 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. You can also find many more orbs in the Orb Registry.


Suggest an edit to this page

Make a contribution
Learn how to contribute