Skip to content

Messaging

Slack

Post review requested, overdue, rejected and approved notices to a Slack channel for each project.

The Slack integration installs a CirCI Slack app into your Slack workspace. Each project then sends the notices it chooses to one channel. It's one-way: CirCI posts messages, and nothing in Slack acts on builds.

You get Where
Review requested, review overdue, build rejected and build approved notices One Slack channel per project
An Open build button on every notice The message itself

CirCI doesn't ship a Slack app of its own. Your instance uses an app you create at api.slack.com, so the Slack tile in the Add integration dialog says Not set up on this server until this is done.

  1. Create a Slack app at api.slack.com, from scratch, in the Slack workspace you want to start with. See Slack's documentation on creating apps.
  2. Under OAuth and Permissions, add the redirect URL PUBLIC_URL/api/integrations/slack/callback.
  3. Add these bot token scopes: chat:write, chat:write.public, channels:read, groups:read. CirCI requests them when someone installs the app.
  4. Copy the app's client ID and client secret into the instance, as described above.
  5. If other Slack workspaces should install the app, turn on public distribution for it in the app's settings in Slack (see Slack's documentation on distributing apps).

An owner or admin of the CirCI workspace opens Workspace settings › Integrations › Add integration › Slack. Slack asks you to allow the app in your Slack workspace, and the return connects it. CirCI stores the bot token it receives, encrypted, and names the integration after the Slack workspace.

If Slack later rejects the token (the app was uninstalled or the token revoked), CirCI flags the integration as needing attention and shows a Reinstall button. No notices go out until you reinstall.

Choose a channel and events for each project

Section titled “Choose a channel and events for each project”

On the Slack integration's page, each project has a Channel and a list of Events. A project without a channel sends nothing.

The channel list comes from Slack: public channels as #name and private channels as name (private). The bot can post to public channels without joining (the chat:write.public scope). For a private channel, invite the CirCI app to the channel in Slack first.

Event Sent when On by default
Review requested Someone is asked to review a build, or asked again Yes
Review overdue A review request passes its target time Yes
Build rejected A reviewer rejects a build Yes
Build approved A reviewer approves a build No

Approvals are opt-in because they're the notices that don't need anyone to act. See Review requests and rules for how requests and due times work.

Every message is a short Slack message with an Open build button that links to the build. The plain text of each message is also set, so Slack notifications and screen readers have something readable.

Each message has a title that starts with an emoji, and a build is named by its project and number (for example Web app #12):

Event Message title Contents
Review requested Review requested (Review requested again for a repeat request) "Asked Reviewer to review Web app #12 on branch", prefixed with who asked when a person did, and "Due" with a date shown in each reader's own time zone
Review overdue Review overdue "Reviewer's review of Web app #12 on branch is overdue", with when it was due
Build rejected Changes rejected Who rejected the changes, and the reason as a quote, cut at 500 characters. The full reason stays in CirCI
Build approved Changes approved Who approved the changes

Names, branches and reasons that come from people are escaped so they can't create Slack mentions or links of their own.

What you see Why, and what to do
The Slack tile says Not set up on this server The instance has no Slack app yet. An instance admin sets the client ID and secret
The server won't start after adding Slack settings Only one of SLACK_CLIENT_ID and SLACK_CLIENT_SECRET is set. Set both or neither
Nothing arrives for a project The project has no Channel, or the event is off. A private channel also needs the CirCI app invited to it in Slack
The integration shows needs attention with Reinstall Slack rejected the token (the app was uninstalled or the token revoked). Press Reinstall; no notices go out until then
Approvals don't show Build approved is off by default. Turn it on for the project
  • Slack as a place to approve or reject: there are no interactive buttons beyond the link to the build.
  • Per-user Slack notifications or direct messages. Messages go to the project's channel only.
  • The build.completed event isn't offered for Slack.

Not yet verified against Slack.