> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# Slack integration Preview

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. If you have any feedback on the feature you can add it to our [Ideas board](https://circleci.canny.io/cloud-feature-requests/p/deeper-integration-with-slack).

Use the CircleCI Slack app to receive workflow notifications in Slack. The app is installed once at the organization level and can then be configured for individual projects.

This guide explains how to:

*   Install the CircleCI Slack app for your organization.
    
*   Link a project to a Slack channel.
    
*   Update notification preferences for a project.
    

## Prerequisites

To install the CircleCI Slack app, you need:

*   CircleCI organization administrator permissions.
    
    *   If you have an organization of type `circleci` permissions are controlled through CircleCI, see the [Roles and Permissions Overview](https://circleci.com/docs/guides/permissions-authentication/roles-and-permissions-overview/) page for more information.
        
    *   If you have an organization of type `github` or `bitbucket` you must be an administrator in the connected GitHub or Bitbucket organization.
        
        To check your organization type, check your organization slug at **Organization settings**  **Overview**. `github` and `bitbucket` type organizations are OAuth authenticated orgs and the organization slug is structured as follows:
        
        *   `github/<your-org-name>` or `gh/<your-org-name>`
            
        *   `bitbucket/<your-org-name>` or `bb/<your-org-name>`
            
        
        An organization slug for a `circleci` type organization is in the following format:
        
        *   `circleci/<UID>`
            
        
    
*   Slack Workspace Admin permissions to authorize the app in your workspace.
    

After the app is installed, any CircleCI organization member with write permissions to a project can:

*   Link that project to a Slack channel.
    
*   Update or remove the channel configuration.
    
*   Enable or disable notifications at the project level.
    

If you do not have the required permissions, the relevant controls are disabled in the CircleCI web app.

## 1\. Install the CircleCI Slack app

The CircleCI Slack app is installed once at the organization level and is then available to all projects in that organization.

1.  In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage.
    
2.  Select **Org** from the sidebar.
    
3.  Select **Slack Integration** from the sidebar.
    
4.  Select **Install CircleCI Slack app**. You are redirected to Slack to authorize the app.
    
5.  In Slack, select the workspace you want to connect and select **Allow**.
    
    If your workspace restricts app installations, you will see a **Request to Install** button. Submit the request. A Slack Workspace Admin must approve it before installation can complete. After approval, return to **Org**  **Slack Integration** and go through the installation flow again to complete setup.
    
6.  Verify that your Slack workspace appears as connected on the **Slack Integration** page.
    

Figure 1. Organization Settings > Slack Integration showing a connected workspace

## 2\. Link a project to a Slack channel

After the Slack app is installed, configure each project to send notifications to a Slack channel of your choice.

1.  In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage.
    
2.  Select **Projects** from the sidebar and locate your project from the list. You can use the search to help.
    
3.  Select the ellipsis  next to your project and select **Project Settings**.
    
    You can also access project settings from each project overview page using the **Settings** button.
    
4.  Select **Slack Notifications** from the sidebar.
    
5.  Select **Add Slack channel**.
    
6.  For public Slack channels you can enter the channel name or channel ID. For private channels you must invite the CircleCI bot to the channel first and then enter the channel ID.
    
    **Pubic channel:**
    
    Enter the channel name or channel ID. To find the channel ID, open the channel in Slack, select the **Open channel details** option from the channel menu and the channel ID is displayed in the modal.
    
    **Private channel:**
    
    First, invite the CircleCI bot to the channel first by running `/invite @CircleCI` in the channel.
    
    Then, enter the channel ID. Find your channel ID by opening the channel in Slack, select the **Open channel details** option from the channel menu and the channel ID is displayed in the modal. If the bot is not invited before you save, you will receive an error.
    
7.  Confirm that the channel ID appears under **Slack channel ID**.
    

To update the channel, select the edit icon  next to the channel ID. To remove it, select the delete icon .

When you save a channel configuration, CircleCI automatically posts a welcome message to the configured channel. This confirms the connection is working. No manual verification is needed.

The message is sent from the CircleCI bot and includes your project name:

CircleCI APP
Welcome! CircleCI is now configured to post updates for <your-project-name> in this channel.
Manage notification settings · View documentation

If you add the same Slack channel to multiple projects, CircleCI sends one welcome message per project.

## 3\. Update notification preferences

Any organization member with write permissions to a project can manage notification settings from **Project settings**  **Slack Notifications**.

1.  In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage.
    
2.  Select **Projects** from the sidebar and locate your project from the list. You can use the search to help.
    
3.  Select the ellipsis  next to your project and select **Project Settings**.
    
    You can also access project settings from each project overview page using the **Settings** button.
    
4.  Select **Slack Notifications** from the sidebar.
    
5.  Scroll to **Events**.
    
6.  Expand the **Workflow Completed** category.
    
7.  Confirm that **On default branch (failed, error, unauthorized)** is enabled.
    

Figure 2. Project Settings > Slack Notifications showing the channel configuration and events

This setting is enabled by default when a channel is first configured. Changes are saved immediately and apply to subsequent workflow activity for that project.

## Manage your Slack integration

Organization administrators can manage the Slack integration from **Org**  **Slack Integration** using two controls:

*   **Toggle**. Enable or disable the Slack integration for the entire organization. Disable the integration to pause notifications for all projects. Individual project settings are preserved and resume when you re-enable the integration.
    
*   **Delete** (trash icon). Remove the CircleCI Slack app from the workspace. Delete the integration to stop all Slack notifications for all projects in the organization.
    
    Deleting the Slack app stops all project notifications across the organization. You must reinstall the app to resume notifications.