Notify a Slack channel of a paused workflow

Cloud

Server v4+

Slack is a real-time collaboration application where team members can work together to perform routine tasks and projects through custom channels and workspaces. When using the CircleCI platform, you may find it useful to enable custom notifications with the Slack app based on specific team needs and requirements.

The CircleCI Slack orb enables you to create different notifications and messages that can be delivered to your desired recipients.

This page shows how to use a built-in job from the Slack orb to notify a Slack channel when there is a paused workflow awaiting approval. For more information on approval see the Using Workflows to Orchestrate Jobs page.

For a full tutorial to get you started with the Slack orb, see Using The Slack Orb to Set Up Slack Notifications.

Configuration walkthrough

Every CircleCI project requires a configuration file called .circleci/config.yml. Follow the steps below to create a complete config.yml file.

1. Specify a version

Every CircleCI config.yml` starts with the version key. This key is used to issue warnings about breaking changes.

version: 2.1

2.1 is the latest CircleCI version, and it ensures you have access to all our latest features and improvements.

2. Use the Slack orb

The Slack orb contains a set of prepackaged CircleCI configurations you can use to implement event-based notifications for your CI/CD pipelines.

To add the orb to your config, insert:

orbs:
  slack: circleci/slack@4.10.1

When using an orb, it is a good idea to check the Orb Registry to ensure you are using the most recent version, or the version that fits best with your project.

3. Create jobs

Jobs are the building blocks of your config. Jobs are collections of steps, which run commands/scripts as required. All of the steps in the job are executed in a single unit, either within a fresh container or Virtual Machine. Learn more about jobs on the Jobs and Steps page.

This guide assumes you have jobs for testing and deploying your project. In the following sections these jobs are test and deploy.

4. Create workflow

A workflow is a set of rules for defining a collection of jobs and their run order. Workflows support complex job orchestration using a set of configuration keys to help you resolve failures sooner. Inside the workflow, you define the jobs you want to run. CircleCI will run this workflow on every commit. Learn more about workflow configuration.

workflows:
  test-hold-deploy: # this can be any name you choose

5. Add jobs to your workflow

Now that we have our workflow, test-hold-deploy, we can use it to orchestrate the running of our test and deploy jobs with a pause requiring manual approval in-between. Refer to the Using Workflows to Orchestrate Jobs page for more details about orchestrating jobs with concurrent, sequential, and manual approval workflows.

We can add an approval job to pause the workflow until manual approval has been given. Notice that the jobs in this workflow are configured to run sequentially using the requires key.

workflows:
  test-hold-deploy:
    jobs:
      - test
      - pause_workflow:
          requires:
            - test
          type: approval
      - deploy:
          requires:
            - pause_workflow

6. Add job to notify Slack channel

The Slack orb has a built-in job, on-hold, which sends a notification to a Slack channel when a workflow is paused, awaiting approval. For details of the default notification templates, refer to the orb README. For details of the various options when using this job, refer to the entry in the Orb Registry.

workflows:
  test-hold-deploy:
    jobs:
      - test
      - slack/on-hold:
          context: slack-secrets
          requires:
            - test
      - pause_workflow:
          requires:
            - test
            - slack/on-hold
          type: approval
      - deploy:
          requires:
            - pause_workflow

In this example, Slack credentials are stored in a context named slack-secrets. For further information on setting this up, see Creating a Context in the Slack orb tutorial.

Full configuration file

version: 2.1

orbs:
  slack: circleci/slack@4.10.1

jobs:
  test:
  ... # define your test job

  deploy:
  ... # define your deploy job

workflows:
  test-hold-deploy:
    jobs:
      - test
      - slack/on-hold:
          context: slack-secrets
          requires:
            - test
      - pause_workflow:
          requires:
            - test
            - slack/on-hold
          type: approval
      - deploy:
          requires:
            - pause_workflow