Slack

This capability is only available to BYOC deployments. Check out our pricing page for more information about subscription plans and the available deployment modes.

The Slack connector integrates groundcover with your Slack workspace. Once configured, groundcover can send monitor notifications to specific Slack channels and enable users to interact with groundcover's agent directly from Slack using @groundcover mentions.

Admin permissions are required to create and manage the Slack connector. Any workspace member can connect their personal Slack account once the connector is set up.

Setting Up the Slack App

Setting up the Slack connector is a one-time process that involves creating a Slack App, providing its credentials, and authorizing it in your workspace.

Step 1: Create the Slack App from Manifest

1. In groundcover, go to Integrations → Connectors and open the Org Connectors tab.

   
2. Select Slack. The setup form opens directly for the first Slack App

   1. If you already have one or more Slack Apps connected, click Add Slack Connector to add another one (see Connecting Multiple Slack Workspaces).

3. Click Create App — this opens Slack's app creation page with a pre-filled manifest containing all the required permissions and configuration.

   
4. In Slack, choose the workspace to install the app in, click Next, review the manifest, and click Create.

You can also reach the same setup form from Integrations → Destinations → Slack App, which is convenient when you're configuring Slack alongside other Destinations like PagerDuty.

You can click View Manifest to inspect the full manifest JSON before creating the app. The manifest includes all required OAuth scopes, event subscriptions, and Socket Mode configuration.

The default manifest includes permissions used by current features and additional unused bot scopes. See Slack App Permissions Reference for their current use, removal impacts, and guidance on reducing permissions.

For more details on creating apps from manifests, see Slack's manifest guide.

Step 2: Upload the App Icon

1. Click Download Icon in the groundcover setup wizard to save the groundcover app icon (PNG).

   
2. In your Slack App settings, go to Settings → Basic Information → Display Information → App Icon & Preview.

   
3. Click Add App Icon and upload the downloaded image.

   

Step 3: Fill in App Credentials

You need three values from your Slack App. All of them are found in your Slack App's settings page.

Field	Where to find it in Slack
Client ID	Settings → Basic Information → App Credentials → Client ID
Client Secret	Settings → Basic Information → App Credentials → Client Secret
App-Level Token	Settings → Basic Information → App-Level Tokens (see instructions below)

Generating the App-Level Token

The App-Level Token is not created automatically — you need to generate it:

1. In your Slack App settings, go to Basic Information → App-Level Tokens.

   
2. Click Generate Token and Scopes.

3. Enter a name (e.g., groundcover).

4. Click Add Scope and select connections:write.

   
5. Click Generate.

6. Copy the token — it starts with xapp-.

The App-Level Token must start with xapp-. groundcover validates it against Slack's API during setup. If the token is invalid or missing the connections:write scope, the setup will fail with an error.

Back in the groundcover setup wizard, fill in:

• Connector Name — A unique label to identify this connector (e.g., groundcover Prod).

• Client ID — From your Slack App credentials.

• Client Secret — From your Slack App credentials.

• App-Level Token — The xapp- token you just generated.

Click Connect to save and proceed to authorization.

Step 4: Authorize the App (OAuth)

After saving the credentials, you are redirected to Slack to authorize the app in your workspace. The standard authorization flow requests the default bot permissions (sending messages, reading channels, etc.). If you need fewer permissions, review Reducing permissions before authorizing.

Once authorization completes:

• The connector status changes to active.

• A Destination of type slack-app is automatically created and bound to your Slack workspace. It appears alongside other Destinations (like Slack Webhook and PagerDuty) in the Notification Routes destination picker and in the monitor wizard. You do not configure this Destination separately — it is managed by the connector.

Connecting Multiple Slack Workspaces

You can connect more than one Slack workspace by repeating the Setting Up the Slack App flow for each workspace:

1. Create a separate Slack App in each workspace (each workspace will need its own Client ID, Client Secret, and App-Level Token).

2. Add each one as a separate connector in Integrations → Connectors → Org Connectors → Slack with a distinct Connector Name (e.g., groundcover Prod, groundcover Staging, groundcover Customer-Success).

3. After OAuth, each connector is bound to its workspace and creates its own slack-app Destination.

When you select a Slack channel in a notification route or monitor, each Slack App appears separately in the picker labeled by its connector name, so you can route alerts to the correct workspace.

A single Slack connector is bound to one workspace. You cannot point two connectors at the same Slack workspace.

Connecting Your Personal Slack Account

After an admin sets up the Slack connector, individual users can link their personal Slack accounts from Integrations → Connectors → My Connections. This enables features like interacting with groundcover's agent via @groundcover mentions in Slack.

See Connecting Your Personal Slack Account for the full walkthrough.

Preview groundcover links in Slack

Paste a link to an individual log or trace into a Slack message to show its details without opening groundcover. Log previews include the log line, level, workload, pod, and timestamp. Trace previews include duration, span and error counts, status code when available, and the slowest span.

The Slack App connector must be active, and the link must point to the same groundcover organization as the connector. Previews use the sharing user's groundcover permissions; if your Slack identity is not connected, Slack prompts you to connect it. Slack can preview up to three recognized groundcover links from one message.

Open a preview to see more details or follow its link back to the corresponding view in groundcover. Links to other pages remain regular Slack links.

Selecting Slack Channels in Notification Routes

After the Slack connector is active, you can route monitor notifications to specific Slack channels.

1. Go to Monitors → Notification Routes.

2. Click Create Notification Route (or edit an existing one).

3. In Step 3 (Rules), click the destination dropdown.

4. Select your Slack App — it is marked with an App tag. A second panel appears listing the available channels in your workspace.

   
5. Search for and select the target channel.

   

1. Click Add Rule to add more rules with different channels or status filters.

Private channels are marked with a lock icon. With chat:write.public, the bot can post to public channels without being added. If you remove that scope, add the bot to each target public channel before sending notifications; selecting a channel here does not add it. For private channels, the bot must first be invited to the channel — only private channels the bot has been added to appear in the picker.

You can create multiple rules to route to different channels based on issue status. For example, send Firing alerts to #critical-alerts and Resolved notifications to #alerts-resolved.

For more details on notification routes, see Notification Routes.

Selecting Slack Channels in the Monitor Wizard

When creating or editing a monitor, you can send notifications directly to Slack channels without using notification routes:

1. Open the monitor wizard (create or edit a monitor).

2. In the Notifications section, select Directly to destinations.

3. Click Set rule.

4. Choose an issue status filter (Firing, Resolved, or both).

5. In the Send to dropdown, select your Slack App.

   
6. Pick a target channel from the drilldown panel. Without chat:write.public, add the bot to each target public channel before sending notifications. Private channels always require an invitation.

7. Click + to add more destinations (additional Slack channels or other Destinations).

Choosing Directly to destinations means this monitor's issues will be skipped by notification routes. If you want notifications to flow through your configured routes instead, select Based on matching notification routes.

The selected channels are persisted in the monitor under notificationSettings.connectedAppParams.<slack-app-id>.channels — see Monitor YAML structure for the full schema.

Issue Graph Previews in Notifications

Slack App notifications include the issue timeline as a PNG by default. The graph is attached shortly after the notification is posted and is updated when the issue resolves.

The issue graph shows the firing, pending, and normal states directly in Slack.

Graph previews are available only for Slack App destinations, not Slack webhooks. They are best-effort and limited to approximately one image per second. When notifications are enabled, delivery is independent: the text notification is sent first and is unaffected if a graph is delayed or skipped.

To disable the graph while creating or editing a monitor, expand Advanced under Issue Details, then enable Hide preview graph in Slack. See Create a new Monitor.

Updating Credentials

If you need to rotate the Client Secret or App-Level Token after the initial setup:

1. Go to Integrations → Connectors and open the Org Connectors tab.

2. Select Slack and open your Slack connector.

3. Enter the new Client Secret and/or App-Level Token. Leave a field blank to keep its current value.

4. Click Save Changes.

If the App-Level Token becomes invalid or is revoked in Slack, the connector will stop receiving events from Slack and move to an invalid token state. Update the token to restore functionality.

Deleting the Connector

1. Go to Integrations → Connectors and open the Org Connectors tab.

2. Select Slack and click the delete action on the Slack connector.

3. Confirm deletion.

A Slack connector that is used by notification routes or monitors cannot be deleted. Remove it from all routes and monitors first.

Troubleshooting

The App-Level Token is rejected during setup

Verify that:

• The token starts with xapp-.

• The token was generated with the connections:write scope.

• The token has not been revoked in Slack.

You can regenerate it in your Slack App under Basic Information → App-Level Tokens.

OAuth authorization fails

• Ensure you are signing into the correct Slack workspace.

• Verify the Client ID and Client Secret match your Slack App's credentials (check for extra spaces when pasting).

User sign-in fails with "workspace does not match"

Each Slack connector is bound to a specific workspace. If a user tries to sign in with a different workspace, the connection will fail. Make sure users sign into the same workspace the admin authorized during initial setup.

Notifications are not being sent to Slack

1. Verify the connector status is active in Integrations → Connectors → Org Connectors.

2. Check that the target channel is selected in your notification route or monitor. For private channels, or public channels when chat:write.public is absent, verify that the bot is a member. Selecting a channel does not add it.

3. Verify the notification route's scope query matches the monitor's labels.

4. Use the Test button in the monitor to send a test notification.

5. Filter traces by workload:dispatch-center in groundcover to inspect delivery attempts.

A private channel does not appear in the channel picker

The bot must be invited to a private channel before that channel appears in the picker. Public-channel delivery without membership requires chat:write.public; without it, add the bot to public alert channels too. Open the channel in Slack and run /invite @groundcover (or use the channel settings → Integrations → Add apps), then reopen the picker.

The channel picker is empty

• If channels were recently created, try closing and reopening the dropdown to refresh the list.

• Verify the Slack App connector status is active in Integrations → Connectors → Org Connectors.

Slack App Permissions Reference

Slack uses separate permissions for the workspace bot, individual users, and the app-level token used for Socket Mode. The tables below describe current use and the impact of removing or declining each permission. Bot permissions support notifications and interactions with the Slack app. Slack MCP user permissions let the agent use Slack tools on your behalf.

Reducing permissions

The nine bot scopes listed under Unused bot scopes are not used by current groundcover features. They are candidates for removal without losing those features. This applies only to bot scopes; permissions with the same names may still support user-token MCP capabilities.

The standard groundcover authorization flow still requests the full default set of bot scopes. Editing the manifest alone does not change that authorization request. If your organization requires a reduced-permission installation, contact groundcover support before creating or reauthorizing the app to confirm the installation procedure for your deployment.

Existing bot and user OAuth tokens retain removed scopes until they are revoked or the app is uninstalled. Reauthorizing alone does not remove those permissions. Revoking the bot token stops notifications and bot API calls; uninstalling the app also disrupts personal connections. Plan the change with support and follow Restoring connections after revocation. See Slack's scope-change guidance.

Keep the permissions needed by the features you use. In particular, public-channel notifications without inviting the bot use chat:write.public, file uploads can require channels:join, and custom message icons use chat:write.customize. These permissions are used by current features and are not part of the unused list.

For personal Slack connections with MCP enabled, users can decline optional permissions during consent. Keep search:read.public, which is required to establish that MCP connection. Declining optional permissions limits the agent's available Slack tools without changing the bot's permissions. Users still need a connected personal Slack account for agent mentions and authenticated link previews.

Choosing permissions for notifications

For text alerts and the public/private channel picker, keep bot scopes chat:write, channels:read, and groups:read. Invite the bot to each target channel. These permissions do not grant access to message history or files, and do not enable agent conversations.

Add permissions for the features you need:

Feature	Additional bot permission	Without it
Issue graph images	files:write	Text alerts continue without uploaded graphs.
Posting to public channels without an invitation	chat:write.public	Invite the bot to each target channel.
Automatically joining public channels for direct file sharing	channels:join	Invite the bot before sharing files to the channel.
Custom message icon	chat:write.customize	Messages use the app's default icon.

For agent conversations, link previews, and other features, use the feature-impact table below. Slack MCP uses separate user permissions and is not required for notifications. The app-level connections:write token remains separate from bot scopes.

Bot files:read is optional. Graph uploads, graph display, and attachment names in message context do not need it. Slack grants file-detail and content access through this scope; groundcover's bot conversation context does not download or analyze file contents.

Follow the support-assisted installation guidance in Reducing permissions. Removing bot scopes can also require removing event subscriptions that depend on them; changing the manifest does not change the standard OAuth request.

Restoring connections after revocation

The bot OAuth token, personal MCP user tokens, and app-level Socket Mode token serve separate purposes. Updating the Client Secret or App-Level Token does not replace revoked bot or user OAuth tokens.

1. If the app-level token was revoked, generate a replacement with connections:write and save it in the connector using Updating Credentials. This restores the credential used to receive Slack events.

2. If the bot token was revoked or the app was uninstalled, reconnect the existing org connector and complete Slack OAuth authorization to install the app and store a new bot token. For reduced permissions, use the procedure agreed with support; the standard flow requests the full default set. Confirm that the connector is active.

3. Users whose personal MCP tokens were revoked must reconnect separately through Integrations → Connectors → My Connections. Reconnecting the org connector does not replace their user tokens.

4. Restore any required channel invitations and send a test notification before relying on the connector for alerts.

Bot Token Scopes

Bot scopes define what the groundcover Slack App can do as a bot in your workspace. History and file permissions are subject to Slack's access rules; they do not grant access to every private channel in the workspace.

Bot permissions and feature impact

These scopes grant access for bot features. The For text notifications column identifies permissions used to send and update text alerts and populate the channel picker. Optional scopes support the additional features described in each row. The bot must be invited to each target channel when chat:write.public is omitted. Coordinate changes with support as described in Reducing permissions, because the standard installation still requests the full default set.

Scope	For text notifications	Permission and current groundcover use	Impact if removed
app_mentions:read	Optional	Receive events when users @mention the groundcover bot, powering the @groundcover Agent	The agent no longer receives channel @mentions.
assistant:write	Optional	Show assistant thread status, such as the agent's thinking indicator	The agent cannot show its thinking indicator or thread status.
channels:history	Optional	Read messages in public channels the bot has joined for agent conversation context	The agent cannot fetch public-channel conversation context. Public-channel message events also require this scope.
channels:join	Optional	Join public channels when sharing uploaded files directly to a channel	The bot cannot join public channels automatically. Invite it before sharing files directly to a channel. Text notifications can still be sent without membership when chat:write.public is retained.
channels:read	Required for public-channel listing	List public channels and their metadata for the notification channel picker	The connector cannot refresh public-channel listings or fetch their metadata for the channel picker.
chat:write	Required to send and update alerts	Send and update monitor notifications, agent replies, and resolved-status messages	The bot cannot send or update notifications or agent replies.
chat:write.customize	Optional	Set the custom groundcover icon on messages sent by the integration	Messages still send, but Slack uses the app's default icon instead of the custom groundcover icon.
chat:write.public	Optional	Send notifications to public channels where the bot has not been invited	The bot cannot send messages to public channels it has not joined. With channels:read retained, those channels can still appear in the picker, but selecting them does not grant permission to send. Add the bot with /invite @groundcover before sending alerts. With channels:history retained, joining also grants channel-history and message-event access; see the access note below.
files:read	Optional	Slack grants access to file details and contents. groundcover's bot conversation context uses attachment names supplied in messages, without downloading or analyzing file contents.	Removes permission for file-detail API calls such as files.info. Attachment names remain available in conversation history and message or mention events. Issue graph uploads, inline display, and updates on resolution do not require this scope. Text notifications continue independently.
files:write	Optional	Upload files, such as issue timeline graph images attached to notifications	Notifications lose uploaded issue graph images. Text notifications continue independently.
groups:history	Optional	Read message history in private channels the bot has been invited to	The agent cannot fetch private-channel conversation context. Private-channel message events also require this scope.
groups:read	Required for private-channel listing	List private channels the bot has been invited to for the channel picker	The connector cannot refresh private-channel listings or fetch their metadata for the channel picker.
im:history	Optional	Receive incoming DM messages and read DM history for agent conversations.	The bot no longer receives incoming DM messages and cannot read DM history, preventing agent conversations in DMs.
im:read	Optional	Read information about DM conversations with the bot	The bot cannot fetch DM conversation metadata.
links:read	Optional	Detect shared groundcover URLs to trigger link previews	Shared groundcover links no longer trigger automatic previews.
links:write	Optional	Display rich previews of groundcover URLs, including log and trace details	The bot cannot display rich groundcover link previews.
reactions:read	Optional	Receive reaction-added events to measure engagement with bot messages	The integration loses reaction-added events used for engagement metrics.
reactions:write	Optional	Add emoji reactions, such as acknowledging an agent request	The bot cannot add acknowledgment emoji reactions.
users:read	Optional	Look up Slack user profiles for agent context and personal account linking when MCP is enabled	New personal Slack connections with MCP enabled fail during account linking. Profile lookups for agent context also fail.
users:read.email	Optional	Include email addresses in Slack profile responses. Account linking uses the signed-in groundcover account's email.	Slack profile responses omit email addresses. Account linking still uses the groundcover identity.

Inviting the bot changes its access as well as where it can post. With channels:history granted, the bot can read messages in public channels it joins. The default manifest also subscribes to message.channels, allowing Slack to deliver new message events from those channels. The agent can use conversation history as context for Slack interactions.

Keeping chat:write.public allows text notifications without channel membership, but does not enforce a posting-only boundary: the file-upload path can join public channels using channels:join. For notifications without granting the groundcover bot channel-history access, use a separate Slack Webhook destination. Webhook destinations do not provide the Slack app's agent interactions or uploaded issue graph previews.

Slack Webhook destinations are available only for BYOC deployments. Each destination sends to the channel configured for its webhook URL; you cannot select a different channel per rule through that destination. To replace Slack App delivery, create one webhook destination per target channel and manually update notification routes or direct monitor destinations. Preserve each rule's Firing/Resolved status filters and select the matching webhook destination. Existing Slack App channel selections do not migrate automatically. Keep the Slack App if you need to select multiple channels through a single destination.

Message updates also change: when Firing and Resolved notifications go to the same channel, the Slack App can update the original firing message on resolution. A Slack Webhook destination sends the resolved notification as a separate message; it does not update the original alert. Keep the Slack App if you need those in-place updates.

Unused bot scopes

The default manifest also includes these nine bot scopes, which are not used by current groundcover features. They are included in anticipation of future features so that enabling those features will not require another permission approval for scopes the app already has.

If you remove one of these scopes and a future feature needs it, an administrator will need to add the scope back in the Slack app's OAuth settings or manifest and reinstall or reauthorize the app in the workspace to grant it. Any required workspace approval must also be completed before that feature can work. See Reducing permissions before changing the app's permissions.

Scope	Permission granted	Impact if removed
bookmarks:read	Read channel bookmarks	No current feature loss.
bookmarks:write	Manage channel bookmarks	No current feature loss.
channels:manage	Create and manage public channels	No current feature loss.
groups:write	Create and manage private channels	No current feature loss.
im:write	Open and start direct-message conversations	No current feature loss.
mpim:read	Read information about multi-person DM conversations	No current feature loss.
pins:write	Pin and unpin messages	No current feature loss.
usergroups:read	Read user groups and their membership	No current feature loss.
usergroups:write	Create and manage user groups	No current feature loss.

User Token Scopes

User permissions apply when individuals connect their personal Slack account. The permissions requested depend on whether Slack MCP is enabled for the deployment.

Slack MCP connections

Slack's MCP server lets the groundcover agent access Slack tools using the connected user's identity and permissions. search:read.public is the only required user scope for this connection. Every other scope in this table is listed under user_optional in the manifest and can be declined during user consent. Available tools depend on the permissions granted and the tools exposed by Slack's MCP server. Some tools may need more than one scope.

The impacts below apply to agent actions through your personal connection; declining these permissions does not remove the workspace bot's permissions or your own access to Slack.

Scope	Agent capability	Requirement	Impact if declined
search:read.public	Search public-channel messages accessible to the user	Required for the MCP connection	The Slack MCP connection cannot be established.
search:read.private	Search private-channel messages accessible to the user	Optional	The agent cannot search private-channel messages through this connection.
search:read.im	Search the user's direct messages	Optional	The agent cannot search your DMs through this connection.
search:read.mpim	Search the user's multi-person direct messages	Optional	The agent cannot search your group DMs through this connection.
search:read.files	Search files accessible to the user	Optional	The agent cannot search Slack files through this connection.
search:read.users	Search for users	Optional	The agent cannot search for Slack users through this connection.
channels:history	Read public-channel message history as the user	Optional	The agent cannot read public-channel message history through this connection.
channels:read	List public-channel conversations and their members	Optional	The agent cannot list public-channel conversations or their members through this connection.
channels:write	Create public channels as the user; it does not grant permission to send messages	Optional	The agent cannot create public channels as you.
chat:write	Send messages as the user	Optional	The agent cannot send messages as you. Bot notifications and replies use separate permissions.
groups:history	Read private-channel message history accessible to the user	Optional	The agent cannot read private-channel message history through this connection.
groups:read	List private-channel conversations and their members	Optional	The agent cannot list private-channel conversations or their members through this connection.
groups:write	Create private channels as the user; it does not grant permission to send messages	Optional	The agent cannot create private channels as you.
im:history	Read the user's direct-message history	Optional	The agent cannot read your DM history through this connection.
im:write	Open direct-message conversations as the user	Optional	The agent cannot open DMs as you.
mpim:history	Read the user's multi-person direct-message history	Optional	The agent cannot read your group-DM history through this connection.
mpim:read	List group-DM conversations and their members	Optional	The agent cannot list group-DM conversations or their members through this connection.
mpim:write	Start multi-person DM conversations; it does not grant permission to send messages	Optional	The agent cannot start group DMs as you.
files:read	Read files accessible to the user	Optional	The agent cannot read existing Slack files as you. You can still upload and share files, including screenshots, in Slack.
canvases:read	Read canvases; also required by Slack's canvas creation and update tools	Optional	The agent loses canvas reading, creation, and editing through this connection.
canvases:write	Create and edit canvases as the user, together with canvases:read	Optional	The agent cannot create or edit Slack canvases as you.
emoji:read	Read the workspace's custom emoji	Optional	The agent cannot list workspace custom emoji through this connection.
reactions:read	Grants permission to read reactions; Slack's published MCP tool list has no dedicated tool for this scope	Optional	Removes reaction-reading permission; does not remove the separate tool for adding reactions.
reactions:write	Add reactions as the user	Optional	The agent cannot add reactions as you.
users:read	Look up user profiles	Optional	The agent cannot look up Slack user profiles through this connection.
users:read.email	Read user email addresses	Optional	Slack user profile lookups through this connection omit email addresses.

Personal connections without Slack MCP

When Slack MCP is disabled, personal connections use Sign in with Slack to link the user's identity. The requested user scopes are openid, email, and profile for sign-in and identity information. They do not grant access to Slack message history or permission to send messages as the user.

The groundcover Agent can still be invoked from Slack. It runs on behalf of the Slack user who invoked it, using the matching groundcover user's RBAC permissions and Agent Mode budget. Monitor notifications can also continue to be sent from groundcover to Slack because those features use the workspace bot connection rather than Slack MCP user permissions.

App-Level Token Scope

The app-level token is separate from bot and user tokens. Its connections:write scope is required to establish Socket Mode connections and receive Slack events. See Generating the App-Level Token.