Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Slack Docs #5932

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Update Slack Docs #5932

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
06b86c3
Update slack.mdx
emilyrohrbough Aug 20, 2024
e81fcef
slack docs updates
emilyrohrbough Sep 24, 2024
13d71b3
run prettier
emilyrohrbough Sep 24, 2024
6586f49
Merge branch 'main' into slack-updates
emilyrohrbough Sep 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
256 changes: 95 additions & 161 deletions docs/guides/cloud/integrations/slack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,228 +1,143 @@
---
title: Integration for Slack
title: Cypress App for Slack
sidebar_position: 40
sidebar_label: Slack
---

The Cypress integration for Slack allows you to see your Cypress test results
directly in your teams' Slack channels.
One of our most-requested Cypress Cloud features, the Cypress app for Slack provides real-time results for your Cypress tests, all in one place—improving remote collaboration and giving wider visibility into test behavior and Application Quality.

<DocsImage
src="/img/guides/cloud/integrations/slack/cypress-slack-integration-channel-feed.jpg"
alt="Cypress notification feed in Slack channel"
width={500}
/>
The Cypress app for Slack allows you to:

## Install the Cypress integration for Slack
- Improve cross-team collaboration by instantly surfacing Cypress results to the teams that need visibility
- Confirm that key tests pass prior to launching new products or features
- Reduce the time it takes to catch failed tests

:::caution
<DocsVideo
src="https://www.youtube.com/embed/hnDPz7dognY?si=PRRy4f5n6f1jzfVJ"
title="Cypress app for Slack"
/>

<strong>Ownership Requirements</strong>
## Getting started

In order to install the Cypress integration for Slack, you must be an admin or
owner of both your Cypress Cloud organization and your Slack workspace.
You need just three things to get started:

:::
- Cypress Cloud account
- Ability to configure Cypress Cloud integrations - you must be an admin or the owner of your Cypress Cloud organization.
- Ability to authorize Slack apps - by default, Slack allows any workspace member to authorize apps, however workspace owners may require app approvals before installation. See this [Slack help article](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace) for more details.

**To install the Cypress integration for Slack:**
## Install the Cypress app for Slack

1. Go to Cypress Cloud
[Organizations page](https://cloud.cypress.io/organizations) or open the
organization switcher.
2. Select the organization you wish to integrate with Slack.
1. In the Cypress Cloud, visit the Integrations page for the organization you wish to integrate with Slack.
2. Click the **Enable** button in the Slack section.
3. A popup window will be displayed requesting permission for Cypress to access the
workspace.
4. After you approve the app permissions, you can choose your Slack workspace and channel to
associate with the installation.
5. The installation is complete!

<DocsImage
src="/img/guides/cloud/organizations/select-cypress-organization.jpg"
alt="Select an organization"
width={500}
/>
Now Cypress will post run results for all projects in your organization to the specified Slack channel.

3. Visit the selected organization's **Integrations** page via the side
navigation.
## Slack configuration

<DocsImage
src="/img/guides/cloud/organizations/navigate-to-organization-integrations.jpg"
alt="Install Cypress Slack from Integrations"
width={500}
/>
The Slack messages can be tailored to match your teams' needs.

4. Click the **Enable** button in the Slack section.
- The Slack app can send results to one or more public or private Slack channels or directly to a specific user
- You can select your notification preferences for when and where run results should be posted.
- The app can be configured at the organization-level and project-level which supports multiple teams working on separate projects.

<DocsImage
src="/img/guides/cloud/integrations/slack/enable-slack-integration.jpg"
alt="Click enable under Slack Integration"
width={1000}
/>
### Per-Organization vs per-project configuration

5. You'll see a popup window that requests permission for Cypress to access the
workspace and allows you to choose your Slack workspace and channel to
associate with the installation. Once you've selected a channel and allowed
access, the installation is complete! Cypress Cloud will post run results for
all projects in your organization to the specified Slack channel.
The following describes where to go to configure Slack for an organization and a project. The remaining sections will describe the supported configuration options.

For more information about how the Cypress integration for Slack collects and
manages your information, please visit our
[Privacy Policy](https://on.cypress.io/privacy-policy).
#### Organization settings

## Per-organization configuration
To share Slack configuration for an organization:

### Add additional Slack channels
1. Navigate to the Integrations page for the organization you wish to configure.
2. Within the Slack integration, click Configure.
3. Configure the app.

You can have Cypress Cloud post run results to an additional channels. To add a
channel:
#### Project settings

1. Navigate to the **Integrations** page for the organization with the installed
integration.
2. Within the Slack integration, click **Configure**.
3. Click **Add Slack Channel**.
4. You'll see a popup window that allows you to choose the channel to associate
with the organization. Cypress Cloud will post run results for all projects
in your organization to the new Slack channel.
To share Slack configuration for a project:

### Set notification preferences
1. Navigate to the Project Settings page for the project you wish to configure.
2. Click on the Integrations tab within the Project Settings page.
3. Configure the app with the Slack Integration section.

By default, Cypress Cloud will post a Slack message to each configured channel
only for failing runs. If you'd like to change these preferences:
### Slack channels

1. Navigate to the **Integrations** page for the organization with the installed
integration.
2. Within the Slack integration, click **Configure**.
3. Under **Notifications**, select your preference for each Slack channel:
You can have Cypress Cloud post run results to specific channels. To add a
channel:

- **Failed runs**: will notify on runs with a failed status.
- **Passed runs**: will notify on runs with a passed status.
- **Flaky tests**: will notify on runs that have an identified flaky test.
1. Navigate to the Slack configuration page
2. Click **Add Slack Channel**.
3. You'll see a popup window that allows you to choose the channel or individual associate
with the organization.
4. Search for and selecting the channel messages should post to.

### Mute a channel
Cypress Cloud will begin to post run results to the channel.

If you want Cypress Cloud to temporarily stop posting Slack messages to a
certain channel, you can **Mute** that channel. This allows you to easily pause
and resume notifications for a specific channel without losing the configuration
you've put in place.
### Direct messages

1. Navigate to the **Integrations** page for the organization with the installed
integration.
2. Within the Cypress integration for Slack, click **Configure**.
3. Under **Actions**, select your **Mute** for each Slack channel you want
muted.
You can have Cypress Cloud post run results to specific user. To post to a user:

### Remove a Slack channel
1. Navigate to the Slack configuration page
2. Click **Add Slack Channel**.
3. You'll see a popup window that allows you to choose the channel or individual associate
with the organization.
4. Search for and selecting the user that messages should be sent to.

You can have Cypress Cloud stop posting notifications to a channel. You can
remove all Slack channels if you'd prefer to disable global notifications
altogether in favor of per-project notifications.
Cypress Cloud will begin to send run results to the this user.

1. Navigate to the **Integrations** page for the organization with the installed
integration.
2. Within the Cypress integration for Slack, click **Configure**.
3. Under **Actions**, select your **Delete** for each Slack channel you want
deleted.

## Per-project configuration

If your organization has multiple teams working on separate projects, you can
tailor the Slack notifications of each project to match your teams' needs.

### Add a new Slack channel

You can have Cypress Cloud post run results for a specific project to an
additional channel.

1. Select your organization in the organization switcher.
<DocsImage
src="/img/guides/cloud/organizations/select-cypress-organization.jpg"
alt="Select an organization"
width={500}
/>
2. Select the project you wish to integrate with Slack.
<DocsImage
src="/img/guides/cloud/projects/select-cypress-project.jpg"
alt="Select a project"
width={600}
/>
3. Go to the project's settings page.
<DocsImage
src="/img/guides/cloud/projects/select-project-settings.jpg"
alt="Visit project settings"
width={400}
/>
4. Scroll down to the **Slack Integration** section.
5. Click **Add Slack Channel**.
6. You'll see a popup window that allows you to choose the channel to associate
with the project.

### Set notification preferences
### Notification preferences

By default, Cypress Cloud will post a Slack message to each configured channel
only for failing runs.

If you'd like to change these preferences:

1. Navigate to the **Integrations** page for the project with the installed
integration.
2. Scroll down to the **Slack Integration** section.
3. Under **Notifications**, select your preference for each Slack channel:
only for failing runs. However, you can select any combination of the followings preferences:

- **Failed runs**: will notify on runs with a failed status.
- **Passed runs**: will notify on runs with a passed status.
- **Flaky tests**: will notify on runs that have an identified flaky test.

:::info

You cannot override the notification preferences for globally configured Slack
integrations.

:::
1. Navigate to Slack configuration page
2. Select the notification preferences for each channel

### Filter notifications by tag
#### Filter notifications by tag

You can filter notifications posted to Slack based on a
When configuring at the project-level, you can filter notifications posted to Slack based on a
[tag](/guides/guides/command-line#cypress-run-tag-lt-tag-gt) the run was
recorded with. This can be helpful to only post notifications on certain runs,
like those to a staging or release environment.

1. Navigate to the **Integrations** page for the project with the installed
integration.
2. Scroll down to the **Slack Integration** section.
3. Under **Tags**, select the **Tag** dropdown for the desired integration and
1. Navigate to the Slack configuration page
2. Under **Tags**, select the **Tag** dropdown for the desired integration and
select which tag to filter.

:::info

Filtering by tags is only available on integrations configured at the project
level.

:::

### Mute a channel

If you want Cypress Cloud to temporarily stop posting Slack messages to a
certain channel, you can **Mute** that channel. This allows you to easily pause
and resume notifications for a specific channel without losing the configuration
you've put in place. You can even mute the messages for the global organization
channels!
you've put in place.

1. Navigate to the **Integrations** page for the project with the installed
integration.
2. Scroll down to the **Slack Integration** section.
3. Under **Actions**, select your **Mute** for each Slack channel you want
1. Navigate to the Slack configuration page
2. Under **Actions**, select your **Mute** for each Slack channel you want
muted.

### Remove a channel
### Remove a Slack channel

You can have Cypress Cloud stop posting notifications to a channel. You cannot
delete the global notification channels from a project.
You can have Cypress Cloud stop posting notifications to a channel. You can
remove all Slack channels if you'd prefer to disable global notifications
altogether in favor of per-project notifications.

1. Navigate to the **Integrations** page for the project with the installed
integration.
2. Scroll down to the **Slack Integration** section.
3. Under **Actions**, select your **Delete** for each Slack channel you want
1. Navigate to the Slack configuration page
2. Under **Actions**, select your **Delete** for each Slack channel you want
deleted.

## Remove the integration

You can completely remove the Cypress integration for Slack from your workspace.
This will remove the @cypress bot from your workspace and will delete all of the
This will remove the `@cypress` bot from your workspace and will delete all of the
Slack configurations you've set in Cypress Cloud. You cannot undo this, but you
will be able to install the Cypress integration for Slack again in the future.

Expand All @@ -231,3 +146,22 @@ will be able to install the Cypress integration for Slack again in the future.
2. Within the Slack Integration, click **Configure**.
3. Click **Uninstall Slack Integration** to uninstall the Cypress integration
for Slack.

## Security and compliance

Review our [Privacy Policy](https://on.cypress.io/privacy-policy) for information about how the Cypress app for Slack collects and
manages your information.

### Authorizations

When authorized, Cypress can:

- View information about a user’s identity
- Post messages to specific channels in Slack & direct message conversations
- Show previews of cloud.cypress.io URLs in messages
- View URLs from cloud.cypress.io

### App scopes

- User token scopes: `links:read`, `links:write`
- Bot token scopes: `chat:write`, `incoming-webhook`, `links:read`, `links:write`