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. 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 of the user area (dark blue top bar) 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.
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.
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.
For a full guide to setting up and using Chunk, see the Chunk Overview and Setup guide.
Slack notifications Beta
| The CircleCI Slack integration is available in preview. This means the product is in early stages and you may encounter bugs, unexpected behavior, or incomplete features. |
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.
To set up Slack notifications for a project, follow the steps in the Slack Integration guide.
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.
-
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.