Today we are releasing the Slack orb v4.0 for CircleCI. It makes pipeline notifications easy to implement and customize. Now with support for Slack’s Block Kit Builder, it also provides a visual way to create endless custom notifications. Check out the slack orb here:

Pipeline on-hold notification example

What’s new?

Simple to use.

Previously, the Slack orb utilized multiple commands and numerous orb parameters to build notifications piece-by-piece. Now, with version 4.0 and above, you can select one of several built-in available templates or customize and import your own notifications visually with Slack’s Block Kit Builder.

In the new Slack orb you will only find a single command notify, and a job on-hold. The notify command is the heart of the orb and can be used to send notifications to any (or multiple) Slack channel based on events like when a CircleCI job has passed or failed.

Built for teams

The new Slack orb authenticates using OAuth, rather than using incoming webhooks as in previous versions. With this change, you can now install a “bot” application in your Slack Workspace for your CircleCI notifications and alert multiple channels from one integration. To setup authentication, be sure to check the GitHub wiki for the Slack orb

Upgrading

Slack orb version 4.0.0 is a complete rewrite of the previous Slack orb with a new feature set and simpler design that is much easier to use. Older versions of the Slack orb will continue to operate and migrating to the new Slack orb experience is entirely optional.

To migrate to the new Slack orb, the old orb must be completely removed as version 4.0 does not share any functionality with previous versions of the orb.

Get started by visiting the GitHub wiki

How does it work?

Orbs are packages of CircleCI configuration which can be imported and utilized in your configuration file.

To jump ahead, you can view the Slack orb in the orb registry, and on GitHub.

The main component of the Slack orb is the notify command, which can be used at the end of any job to send notifications based on the status of that job.

 - slack/notify:
      event: fail
      template: basic_fail_1

There is now a single notification command with an event parameter. The notify command should be placed at the end of any job as it will always run and can detect the current status of the job.

You can specify notifications to always send or to send on fail or pass. If a branch_pattern parameter is specified, the current branch must also match the pattern to send the notification.

For the message body, you can select one of the preconfigured templates included with the orb, or create your own custom notification.

You can see a full list of available templates on the GitHub Wiki.

Slack Orb Templates

By default, the Slack orb will attempt to post to the channel specified by the $SLACK_DEFAULT_CHANNEL environment variable, but you can also select one or more channels via the channel parameter.

A working example

Here is a semi-realistic example of a test and deploy workflow on CircleCI. It has one job which tests the application on every commit (test), and a deployment job which only runs on a tagged commit (deploy).

In this example, we will place our workflow (test-and-deploy) On hold prior to deployment, and wait for a manual approval. After an engineer manually approves the workflow, the deployment job will execute. For this workflow, we want to set up three potential notifications for Slack:

  • A notification when the workflow is placed on-hold
  • A notification if the deployment fails
  • A different notification if the deployment succeeds

The following usage example is pulled directly from the orb registry.

This configuration makes two assumptions:

  1. You have stored your OAuth token as $SLACK_ACCESS_TOKEN in a restricted context named slack-secrets
  2. You have defined the $SLACK_DEFAULT_CHANNEL as either a project environment variable, or within the slack-secrets context.
 version: 2.1
 orbs:
   slack: circleci/slack@4.0
 jobs:
   # This "test" job will run on every commit (as per our workflow)
   # We are ok with no notifications sent for this job.
   test:
     docker:
       - image: cimg/base:stable
     steps:
       - run: echo "test my app"
   # This "deploy" job will only run on a tagged commit (as per our workflow)
   # We want to be alerted if this job fails and also when it succeeds.
   deploy:
     docker:
       - image: cimg/base:stable
     steps:
       - run: echo "deploy my app"
       # In the event the deployment has failed, alert the engineering team
       - slack/notify:
           event: fail
           template: basic_fail_1
           mentions: "@EngineeringTeam"
       # When there is a successful deployment, send a notification with a different template.
       - slack/notify:
           event: pass
           template: success_tagged_deploy_1
 workflows:
   test-and-deploy:
     jobs:
       # We want the test job to run on all commits, so we will list it with no filters.
       - test
       # When we are on a tagged commit (example "v1.0.0"), we want to also place the workflow on-hold, pending manual approval for deployment.
       # We will also make use of the Slack orb's "on-hold" job to notify us to this on-hold workflow, making it easy to respond.
       - slack/on-hold:
          context:
            - slack-secrets
          requires:
            - test
          filters:
            tags:
              only: /^v.*/
       # Jobs with the type of "approval" act as place holders to pause the workflow, the job name does not matter.
       # Wait for both the test job and for the notification to send before pausing.
       - pause_workflow:
          type: approval
          requires:
            - test
            - slack/on-hold
          filters:
            tags:
              only: /^v.*/
       # The deploy job will continue once the workflow has been manually approved.
       - deploy:
          context:
            - slack-secrets
          requires:
            - pause_workflow
          filters:
            tags:
              only: /^v.*/

Creating custom notifications

Previously, creating custom notifications involved using many parameters. They were limited and difficult to configure. Now, you can create nearly any notification imaginable with only a single parameter, and notifications are designed visually using Slack’s Block Kit Builder. You can start with any of Slack’s built-in templates, or start fresh and design your own.

Slack Block Kit Builder example

On the right side of the screen above, you get the payload that contains the text we feed to the Slack orb via the custom parameter (as an alternative to the template parameter).

- slack/notify:
    event: always
    custom: |
      {
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "Current Job: $CIRCLE_JOB"
            }
          },
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "Write some text here"
            }
          }
         ]
        }

Before copying the payload, customize the look of your notification using the components on the left side of the screen. Environment variables can be used in any text fields and the values will be replaced at runtime.

For more information and examples, check out the GitHub Wiki and the orb registry page.

Join The Community

Orb developers and consumers are welcome to join our Discuss forum! We would love to hear from you, whether you have questions, comments, or concerns about the Slack orb. Need to file an issue or want to request a feature? We’d love to hear from you on GitHub as well.