Menu
Open source

Slack integration for Grafana IRM

The Grafana IRM Slack integration incorporates your incident response workflow directly into your Slack workspace, helping your team focus on alert resolution with less friction.

Note

The OnCall Slack app has been rebranded as the Grafana IRM Slack app, which now has incident management features. The legacy Incident Slack integration is being deprecated.

If you have an existing installation of the legacy Slack integrations, refer to the migration instructions for more information on how to migrate to the Grafana IRM Slack integration.

Key features and benefits

Integrating your Slack workspace allows users and teams to be notified of alerts directly in Slack with automated alert escalation steps and user notification preferences. Users can take a number of alert actions directly from Slack, including acknowledging and resolving alert groups, adding resolution notes, and more.

Refer to the following sections to learn more:

When it comes to incidents, users can declare, collaborate on, and manage incident-worthy events without leaving Slack. They can also automatically create incident-specific channels, track the timeline of events, interact with incidents via Slash commands, and more.

Refer to the following sections to learn more:

Before you begin

To install the Grafana IRM Slack app:

  • You must have an Admin role in Grafana IRM
  • You must be a Slack workspace admin or owner
  • Allow Grafana IRM to access your Slack workspace

Once your IRM account has been added to your Slack workspace, Admins and Editors can configure escalation chains and other notifications to route to designated Slack channels.

In order to use the Slack slash command /grafana, you must be an IRM user with a linked Slack account. To learn more, refer to Connect your Slack user to Grafana IRM.

Install Slack integration for Grafana IRM

Currently, the Grafana IRM Slack integration can be installed from Grafana OnCall or Grafana Incident. Installing the integration in either location will automatically install it for the other.

Note

If you already have the OnCall or Incident Slack integration installed, use the instructions in Migrate to the IRM Slack integration.

Follow these steps to install the Slack integration from Grafana OnCall:

  1. Navigate to the Settings tab in Grafana OnCall.
  2. From the ChatOps tab, select Slack in the side menu.
  3. Click Install integration.
  4. Once redirected to the Slack connection page, verify the Slack workspace is correct or Add another workspace.
  5. If needed, provide your Slack workspace URL and sign with your Slack credentials.
  6. Follow the Slack prompts to review permissions and specify a default channel.
  7. Click Allow to give Grafana IRM permission to access your Slack workspace.

Follow these steps to install the Slack integration from Grafana Incident:

  1. Navigate to the Integrations tab in Grafana Incident.
  2. Click the Slack IRM tile and then click Install Integration.
  3. Once redirected to the Slack connection page, verify the Slack workspace is correct or Add another workspace.
  4. If needed, provide your Slack workspace URL and sign with your Slack credentials.
  5. Follow the Slack prompts to review permissions and specify a default channel.
  6. Click Allow to give Grafana IRM permission to access your Slack workspace.

For more information about the required permissions, refer to the Permissions section.

Migrate to the Grafana IRM Slack integration

The Grafana IRM Slack integration combines the features of both OnCall and Incident into a single app. The OnCall Slack app has been rebranded as the Grafana IRM Slack app and now includes incident management capabilities.

This integration is IRM-wide, meaning that once the Grafana IRM Slack integration is installed or re-installed in OnCall, it will automatically be available for use in Incident, and vice versa. The same applies to the uninstall process—uninstalling the IRM app from OnCall will also remove it from Incident.

There are two ways to upgrade to the new integration, depending on your current installation.

Migrate from the OnCall Slack app to the IRM Slack app

To upgrade from the OnCall Slack integration to the Grafana IRM Slack integration, you only need to approve the additional permissions required for Incident management functionality. Migrating to the IRM Slack app will not affect your existing OnCall Slack-related configuration, including channels, users, and schedules.

Note

The /escalate command is deprecated, please use /grafana escalate instead. Refer to Available Slack commands for more information.

From OnCall, follow these steps to upgrade:

  1. Navigate to the Settings tab in Grafana OnCall.
  2. From the ChatOps tab, select Slack in the side menu.
  3. Click Migrate
  4. Once redirected to the Slack connection page, verify the Slack workspace and follow the Slack prompts to review permissions and specify a default channel.
  5. Click Allow to reauthorize Grafana IRM to access your Slack workspace with additional permissions.

Migrating to the Grafana IRM Slack integration requires the following additional permissions:

  • Bookmarks:read
  • Bookmarks:write
  • Channels:manage
  • Groups:write
  • Pins:read
  • Reactions:read
  • Incoming-webhook

Refer to the Permissions section for detailed information.

Migrate from the Incident Slack app to the IRM Slack app

The Grafana Incident Slack integration is now considered legacy, and you will need to migrate to the new Grafana IRM Slack integration by installing the updated Grafana IRM Slack app.

During this migration, your existing Incident Slack settings, including incident announcements and automatic channel creation, will be preserved. The new Grafana IRM Slack app will be installed, along with the /grafana incident command. You will still be able to manage incidents that were started before the migration using the legacy app and the /incident command.

From Incident, follow these steps to migrate:

  1. Navigate to the Integrations tab in Grafana OnCall.
  2. Click the Slack IRM tile and then click Install Integration.
  3. Once redirected to the Slack connection page, verify the Slack workspace and follow the Slack prompts to review permissions and specify a default channel.
  4. Click Allow to authorize Grafana IRM to access your Slack workspace.

Refer to the Permissions section for more information.

Connect your Slack user to Grafana IRM

For users to gain full access to Grafana IRM functionality in Slack, follow these steps to map your Grafana IRM user account to your Slack user account:

  1. In Grafana OnCall, navigate to the Users tab and click View my profile.
  2. Under the User Info tab, find the Slack username section and click Connect.
  3. Follow the prompts to verify and link your Slack account.

Configure channels and notifications

Grafana IRM provides flexible configuration options to tailor Slack notifications to your team’s needs. This section outlines how to set up escalation chains, user notifications, on-call notifications, and incident channels within Slack.

Configure Escalation Chains with Slack notifications

After setting up your Slack integration, you can configure escalation chains to send notifications via Slack for alerts in Grafana OnCall.

There are two Slack notification methods that can be integrated into escalation chains:

  • Notify all members of a Slack channel
  • Notify a specific Slack user group

To configure these in your escalation chains:

  1. In Grafana OnCall, navigate to the Escalation Chains tab.
  2. Select an existing escalation chain or create a new one by clicking + New escalation chain.
  3. Use the dropdown under Add escalation step to choose and configure your Slack notification preferences.

Configure user notifications policies with Slack mentions

You can receive alert notifications directly via Slack mentions, ensuring that critical alerts reach you immediately:

  1. From the Users tab in Grafana OnCall and click Edit next to the user you want to configure.
  2. In the User Info tab, click + Add Notification step.
  3. Choose Notify by in the first dropdown, then select Slack mentions in the second dropdown to receive notifications through Slack mentions.

Configure on-call notifications in Slack

The IRM Slack integration also supports automated notifications for on-call shifts, helping teams stay informed of their duties. Admins can set up these notifications in the Notification Preferences section:

  1. When an on-call shift notification is sent to a person or channel, click the gear icon to open Notifications preferences.
  2. Configure the notification behavior for future shifts according to your team’s preferences.

Configure Incident Slack channels

Grafana IRM allows you to customize the names of incident-specific Slack channels by setting prefixes, making it easier to organize and search for incident channels. To customize Slack channel prefixes:

  1. Click Incident in the left-side menu.
  2. Go to Settings.
  3. Scroll down to the Prefixes section in the Settings page.
  4. Click + Add Prefix and provide a name and description.
  5. Edit any existing prefixes as needed, then click Update.
  6. Once your prefixes are defined, you can choose which prefix to use when declaring an incident in Grafana Incident.

Configure Incident announcements

Incident announcements help keep your team aware and informed during critical events. Configure these announcements to ensure that stakeholders are kept up-to-date in Slack during an incident.

To configure Incident announcements:

  1. Navigate to Incident in the left-side menu, then click Integrations.
  2. Click Slack IRM to open the Slack IRM integration page.
  3. Select the Slack channel where you want to send notifications. You can either choose from the dropdown menu or manually add your Channel ID. The Channel ID can be found in the Slack channel’s About tab.
  4. Define the incident-specific fields:
  • Incident type: Choose whether the incident is internal or private.
  • Include incidents: Specify which types of incidents to announce—options include all incidents, drills, or non-drills.
  1. Apply filters to your incident announcements to tailor the notifications to specific channels:
  • Incident filter: For example, you might filter by label, such as label: 'squad:datasources'.

Manage Slack attachments

When you use the 🤖 emoji reaction on a Slack message containing a file, the file is securely copied to Grafana Cloud storage. This ensures your incident timeline remains intact, even if the file is later deleted from Slack. Here’s how it works:

  • File retention: Control attachment retention in your incident timeline. Removing the 🤖 reaction will delete the attached files from Grafana Cloud storage.
  • Incident web app: Deleting an item from the timeline within the Incident web app also removes the associated file from Grafana Cloud storage.
  • File size limit: Files in Grafana Incident are limited to 100MB. Files too large to persist will still be accessible via a link to the source file in Slack.

Available Slack commands

Note

The /escalate and /incident Slack commands have been deprecated. Use /grafana to learn more.

The /grafana Slack commands allow users and teams to respond to alert groups and collaborate on incidents directly from Slack.

Tip

Use the 🤖 robot emoji Slack reaction to add important messages to the incident timeline.
CommandDescription
/grafanaList of all /grafana commands
/grafana stacksList all available stacks
/grafana set-stackSet your default stack
/grafana escalatePage a user or a team
/grafana incidentPrefix for Incident-related commands
CommandDescription
/grafana incident newCreate new incident
/grafana incident new “title”Create new incident with severity
/grafana incident listList all active incidents
/grafana incident rolesFind out who’s involved
/grafana incident talkSet up a collaboration space
/grafana incident statusGet a live inline update
/grafana incident severitySet the incident severity
/grafana incident severity majorUpdate the incident severity to major
/grafana incident tasksCreate, assign and manage tasks
/grafana incident tasks helpMore information about tasks
/grafana incident task add 'deploy new release'Add a new task
/grafana incident task add 'deploy new release' @bobAdd a new task and assign to @bob
/grafana incident tasks listView current tasks
/grafana incident notesAdd and view incident notes
/grafana incident notes helpMore information about notes
/grafana incident note add "customers notified"Add a new note
/grafana incident notes listView current notes

Permissions scope and purpose

The Grafana IRM Slack app only requests permissions that are essential to its proper function and integration with Slack. Refer to the Slack documentation for more information on permission scopes.

By granting access to the app, you are authorizing Grafana IRM the following permissions in your Slack workspace:

Workspace and user access

PermissionDescriptionPurpose
team:readView the workspace name, email domain, and iconUsed for identification and to establish an association with your workspace
users:readView people in a workspaceUsed to find users by email and facilitate account matching between Grafana and your workspace
users.profile:readView profile details about people in a workspaceThis permission enables us to fetch profile data, such as Slack handles and avatars
users:writeSet presence for Grafana IRM Slack appAllows @GrafanaIRM to be added to your workspace
usergroups:readView user groups in a workspaceRequired to connect on-call schedules and escalation chains to Slack user groups
usergroups:writeCreate and manage user groupsRequired to connect on-call schedule and escalation chains to Slack user groups
incoming-webhookCreate one-way webhooks to post messages to a specific channelUsed to display a channel picker in the installation sequence

Public channel access

PermissionDescriptionPurpose
channels:readView basic information about public channelsUsed when adding a new channel to an escalation chain and to locate and update incident-specific channels
channels:manageManage public channels that Grafana IRM has been added to and create new onesAllows the app to create new channels and invite users to these channels
channels:joinJoin public channels in a workspaceAllows @GrafanaIRM to join channels
channels:historyView messages and other content in public channels that Grafana IRM has been added toAllows @GrafanaIRM to list messages in channels where the app has access to be included in the resolution notes
bookmarks:readList bookmarksUsed to access bookmarks, such as PIR documents and Google Meet links, related to incidents
bookmarks:writeCreate, edit, and remove bookmarksNecessary for managing incident-related bookmarks, including PIR documents and Google Meet links
files:readView files shared in channels and conversations that Grafana IRM is a part ofFor incident-related file sharing and collaboration within authorized channels
files:writeUpload, edit, and delete files as Grafana IRMUsed to upload image attachments so they appear in the Incident timeline
pins:readView pinned content in channels and conversations that Grafana Incident has been added toUsed to access and display pinned content related to incidents

Private channel access

PermissionDescriptionPurpose
groups:readView basic information about private channels that Grafana IRM has been added toUsed to access information from private incident-specific channels
groups:writeManage private channels that Grafana IRM has been added to and create new onesRequired to create private incident-specific channels for private incidents
groups:historyList messages from private incident-specific channelsAllows @GrafanaIRM to list messages from private incident channels to be included in the resolution notes
usergroups:writeCreate and manage user groupsRequired for connecting on-call schedules to Slack user groups
usergroups:readView user groups in a workspaceRequired for connecting on-call schedules to Slack user groups

Message and conversation access

PermissionDescriptionPurpose
app_mentions:readView messages and other content in public channels that Grafana IRM is a part ofEnables the app to read messages and related content within authorized channels
chat:writePost messages in approved channels & conversationsAllows @GrafanaIRM to post messages to Slack
chat:write.customizeSend messages as Grafana IRM with a customized username and avatarAllows @GrafanaIRM to post messages to Slack
chat:write.publicSend messages to channels GrafanaI RM isn’t a member ofAllows @Grafan IRM to post messages to Slack
reaction:readView emoji reactions and their associated content in channels and conversations that Grafana IRM has been added toAllows @GrafanaIRM to monitor message events for the 🤖 emoji to be included in the incident timeline
reaction:writeAdd and edit emoji reactionsRequired to include messages with the 📝 emoji on resolution notes
im:readView basic information about direct messages that Grafana IRM has been added toEnables the app to send alert group notifications to users via direct message
im:writeStart direct messages with peopleUsed to notify users about alerts via direct message as well as invite users who create an incident to the incident channel
im:historyView messages and other content in direct messages that Grafana IRM has been added toAllows @GrafanaIRM to monitor message events in direct messages that it’s a part of
mpim:historyView messages and other content in group direct messages that Grafana IRM has been added toAllows @GrafanaIRM to monitor message events in group direct messages that it’s a part of