Notifications overview
CircleCI offers multiple ways to receive notifications about your builds, workflows, and deployments. You can configure email notifications for your own work and set up Slack notifications for team channels. You can receive alerts about deployment status and Chunk usage, and when a workflow pauses and waits for a manual approval. You can also designate contacts for organization-wide security and technical communications. Notifications can be configured at the user level, project level, and organization level.
This page explains how to configure email notifications, Slack notifications, and organization-level contacts.
User-level notifications
Configure your notification preferences, including the email address to use and the notifications category you would like to receive.
| Your available email addresses depend on how you log in. If you use email and password, you will have a single email address. If you log in via GitHub or Bitbucket, you will see all email addresses associated with your connected account. To add or remove email addresses from your account, see the Manage Email Addresses guide. |
Default email address for notifications
CircleCI uses your "default" email address to send mandatory communications, which include:
-
System and security messages.
-
Billing and account updates.
-
Deprecation notices.
To set or change your default email address, follow these steps:
-
In the CircleCI web app, select your avatar at the top right corner in the web app.
-
Select User Settings.
-
Select Notifications from the sidebar.
At the top of the page you can select the default email address for your notifications.
Build notification preferences
Under "Build notification preferences" you can select between your saved email addresses per organization. You can also select Don’t send email notifications for a specific organization as required.
If you are a member of multiple organizations, you can specify a different email address for each organization. Use the dropdown menus to select from your available email addresses.
Notification categories
You can configure your preferences for notification categories at . The following notification categories are available:
My work
The My work category sends notifications for builds that you personally triggered. Use this to track your own commits and workflow runs. This category also notifies you by email when a workflow you triggered goes on hold at an approval job. For more detail, see the Approval Job Notifications section.
You can filter which notifications you receive based on build status. The "On default branch (any status)" filter overrides individual status filters. For example, if you enable "On default branch (any status)" but disable "Cancelled" notifications, you will still receive notifications for cancelled workflows on your default branch. This includes workflows that are automatically cancelled when approval jobs expire after 90 days.
Available filters:
-
On default branch (any status).
-
On default branch (failed, error, unauthorized).
-
Failed
-
Succeeded
-
Cancelled
-
Unauthorized
-
Error
Email notifications appear as follows:
Deployment notifications
If you use the CircleCI release agent for deployments, you can receive notifications when a deployment is inconclusive. This helps you catch deployment issues early and investigate problems before they affect production. An inconclusive deployment typically means the release agent could not determine whether the deployment succeeded or failed.
For more information, see the Release Agent Overview guide.
Followed projects
The Followed projects category sends notifications for any build in a project that you have followed, regardless of who triggered it. Use this to monitor team projects and stay informed about the overall project health. This category also notifies you by email when a workflow in a followed project goes on hold at an approval job. For more detail, see the Approval Job Notifications section.
You can filter which notifications you receive based on build status. The "On default branch (any status)" filter overrides individual status filters. For example, if you enable "On default branch (any status)" but disable "Cancelled" notifications, you will still receive notifications for cancelled workflows on the default branch. This includes workflows that are automatically cancelled when approval jobs expire after 90 days.
Available filters:
-
On default branch (any status).
-
On default branch (failed, error, unauthorized).
-
Failed
-
Succeeded
-
Cancelled
-
Unauthorized
-
Error
Chunk notifications
Chunk by CircleCI assists with CI/CD related tasks through a natural language chat interface and task scheduling. You can receive notifications when a teammate attempts to use Chunk. This allows you as an organization administrator to evaluate and enable Chunk for your organization.
Chunk also sends an email digest at 09:00 UTC every Monday summarizing your team’s activity. The digest shows completed tasks, PRs opened, and failed tasks at a glance, plus a list of the most recent PRs awaiting your review. To disable the digest, select your avatar in the top right corner of the web app. Open User Settings, select Notifications from the sidebar, scroll to the Chunk section, and toggle off Digest.
For a full guide to setting up and using Chunk, including the email digest, see the Email Digest section of the Chunk Overview and Setup guide.
Slack notifications Beta
Configure Slack notifications at the project level to send workflow status updates to your team’s Slack channels. This allows your entire team to stay informed about build status without individual email notifications. CircleCI also sends a message to the project’s Slack channel when a workflow goes on hold at an approval job. For more detail, see the Approval Job Notifications section.
To set up Slack notifications for a project, follow the steps in the Slack Integration guide.
Approval job notifications
When a workflow reaches an approval job, it pauses until someone manually approves it. This state is called on hold. CircleCI sends an approval job notification when a workflow goes on hold, so it can be reviewed and approved without delay.
For more information on approval jobs, see the Hold a Workflow for a Manual Approval section.
Who is notified
Approval job notifications are delivered through the same categories as your other notifications:
-
Email to the user who triggered the pipeline, through the My Work category.
-
Email to followers of the project, through the Followed Projects category. Followers can enable these emails in their user notification settings.
-
Slack to the project’s configured Slack channel, through Slack Notifications. This requires an active Slack Integration for your organization.
Organization-level contacts
Organization-level contacts are different from user-level notifications. These contacts are used by CircleCI to reach designated administrators during security events, deprecation notices, and platform-level changes. They ensure your organization has a reliable point of contact for critical communications that affect your entire team, not just individual developers.
Set organization-level contact email addresses for the following purposes:
-
Security contacts. Used during security events if no other key contact exists. A maximum of 5 email addresses can be stored.
-
Technical contacts. Used for deprecation notices and platform-level changes directed at the organization. A maximum of 5 email addresses can be stored.
To set up organization-level contacts you must be an organization administrator. Follow these steps:
-
In the CircleCI web app, select your org from the org cards on your user homepage.
-
Select Org from the sidebar to open your organization settings page.
-
Scroll to the manage security and technical contacts sections.
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. For more information on using the Slack orb, see Using the Slack Orb.