CircleCI Logo
Navigation Menu Icon

Notifications overview

Language Icon 4 days ago
Cloud
Contribute Go to Code

CircleCI offers integrated email notifications. IRC and Slack notifications can also be configured using orbs. Slack and email notifications are delivered on the successful completion or failure of a Workflow. IRC notifications are delivered for each job. Consider the minimal CircleCI config below:

version: 2.1
jobs:
  build:
    docker:
      - image: cimg/base:2021.04
    steps:
      - checkout
      - run: <command>
  test:
    docker:
      - image: cimg/base:2021.04
    steps:
      - checkout
      - run: <command>
workflows:
  version: 2.1
  build_and_test: # < Slack and email notifications are sent for workflows
    jobs:
    # IRC notifications are sent for each job.
      - build
      - test

Setting and changing email notifications

To set or change your default email address, visit the Notifications page of the CircleCI application. If you are a member of multiple organizations, you can specify a different email address for each organization using the dropdown for each org.

Screenshot showing how to change default email address and choose notifications
Figure 1. Default email

You can also configure your preferences for different categories here:

  • My work - you receive an email every time a build you triggered finishes.

  • Followed projects - you receive emails for any build that has finished in a project that you have followed.

You can further filter the notifications you receive based on the status of the build as below:

  • On default branch (any status).

  • Failed

  • Succeeded

  • Cancelled

  • Unauthorized

  • Error

Screenshot showing how to change which notifications to receive
Figure 2. Notification categories

Email notifications appear as follows:

Example success email notification
Figure 3. Success email
Example failure email notification
Figure 4. Failure email

Sending notifications with orbs

You can use orbs to integrate notifications into your configuration. CircleCI offers a Slack orb and an IRC orb. Several third-party orbs are also available. Search the orb registry to see what other orbs are available.

Using the Slack orb

Using the CircleCI Slack orb, you can integrate and customize Slack notifications directly from your config.yml file. The following config is an example of notifying a Slack channel with a custom message:

version: 2.1
orbs:
  slack: circleci/slack@4.9.3
jobs:
  notify:
    docker:
      - image: cimg/base:2021.04
    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:
          context: slack-secrets

See Using the Slack Orb for a full tutorial with examples.

CircleCI’s Slack orb can be used for other types of notification, including notifying a Slack channel of a pending approval. For more information and to view usage examples, see the CircleCI Slack orb page.

Using the IRC orb

The IRC orb is similar to the Slack orb, but only has one main feature: sending custom IRC notifications from CircleCI. Consider this example configuration:

version: 2.1
orbs:
  irc: circleci/irc@0.2.0
jobs:
  build:
    docker:
      - image: <Docker image>
    steps:
      - checkout
      - irc/notify:
          server: <IRC-server-to-connect-to> # default: IRC_SERVER environment varible.
          port: <6667> # default: 6667 if left blank.
          channel: <the IRC server to post in> # required parameter
          nick: <Your IRC nickname> # default: `circleci-bot`
          message: <Build complete!> # default: "Your CircleCI Job has completed."
workflows:
  your-workflow:
    jobs:
      - build

Replace the values in brackets (< >) with your own details.

See also