GitHub + integration for Slack

About

The GitHub integration for Slack gives you and your teams full visibility into your GitHub projects right in Slack channels, where you can generate ideas, triage issues and collaborate with other teams to move projects forward. The code for this integration is not open-source, and is not available in this repo.

Installing the GitHub integration for Slack
- Requirements
- Installation
Getting Started
- Subscribing and Unsubscribing
- Authorization
Features
GHES Integration
Need help?
License

Installing the GitHub integration for Slack

Requirements

GHEC on GitHub.com - GA

This app officially supports GitHub.com (which includes our GitHub Enterprise cloud-hosted offering) and Slack.com.

GHEC with data residency on ghe.com - GA

Please install the data residency compatible version of the app here.

GHES - GA

GHES integration with Slack.com is now GA with GHES 3.8. The detailed steps for integrating Slack with GHES can be found here.

Installation

Install the GitHub integration for Slack. After you've signed in to your Slack workspace, you will be prompted to give the app access:

After the app is installed, and once you've added the GitHub integration to the relevant channels using /invite @github, you will see previews of links to GitHub issues, pull-requests, and code rendered as rich text in your workspace.

Getting Started

Once you install the app, you can not interact with GitHub app as a Personal app or access from a channel. Once the app is installed in the workspace, the GitHub app is enabled in all the public channels. For private channels, you need to explicitly invite /invite @github.

At this point, your Slack and GitHub user accounts are now linked. You will be prompted to connect to GitHub. This is a primary step required to access the app. Alternatively, we can also connect by running /github signin.

And once you connect, you will see the next steps and list of functionalities available for you.

Subscribing and Unsubscribing

The /github slash command also accepts a subscribe argument that you can use to subscribe to an Organization or Repository's activity /github subscribe <organization>/<repository>.

If you originally gave the app access to "All repositories" and you've created a new private repository on GitHub after installing the GitHub integration for Slack, the /github subscribe command will work automatically on your new repository. If you installed the app on a subset of repositories, the app will prompt you to install it on the new repository.

The /github slash command also supports unsubscribe. To unsubscribe to notifications from a repository, use /github unsubscribe <organization>/<repository>

Authorization

By granting the app access, you are providing the following authorizations to your GitHub and Slack accounts:

Slack Permission Scopes

|Permission scope|Why we need it| |---|---| |Access private conversations between you and the App | To message you with instructions. | |View links to GitHub.com in messages| To render rich links from github.com| |Add link previews to GitHub.com to messages| To render rich links to github.com| |Add slash commands| To add the /github slash command to your Slack workspace | |View the workspace or organization's name, email domain, and icon| To store subscriptions you set up| |Post messages as the app| To notify you of activity that happens on GitHub, in Slack|

GitHub Permission Scopes

|Permission scope|Why we need it| |---|---| |Read access to code| To render code snippets in Slack| |Read access to actions, commit statuses, checks, discussions, issues, metadata, pull requests, and repository projects | To render previews of links shared in Slack| |Write access to actions, issues, deployments, and pull requests | To take action from Slack with the /github command and directly from messages|

Features

Subscribe to an Organization or a Repository

On repositories, the app notifies of open, close, and re-open events on pull requests and issues in repositories you've subscribed to. It also notifies of any push directly to the repository's default branch.

Customize your notifications

You can customize your notifications by subscribing to activity that is relevant to your Slack channel, and unsubscribing from activity that is less helpful to your project.

Settings are configured with the /github slash command:

/github subscribe owner/repo [feature]
/github unsubscribe owner/repo [feature]

These are enabled by default, and can be disabled with the /github unsubscribe owner/repo [feature] command:

issues - Opened or closed issues
pulls - New or merged pull requests, as well as draft pull requests marked "Ready for Review"
commits - New commits on the default branch (usually main)
releases - Published releases
deployments - Deployment status updates.

These are disabled by default, and can be enabled with the /github subscribe owner/repo [feature] command:

workflows - Actions workflow run notifications
reviews - Pull request reviews
comments - New comments on issues and pull requests
branches - Created or deleted branches
commits:* - All commits pushed to any branch
+label:"your label" - Filter issues, pull-requests and comments based on their labels.
discussions - Discussions created or answered

You can subscribe or unsubscribe from multiple settings at once. For example, to turn on activity for pull request reviews and comments:

/github subscribe owner/repo reviews comments

And to turn it back off:

/github unsubscribe owner/repo reviews comments

Branch filters for commit

Branch filters allow filtering commit notifications. By default when you subscribe for commits feature, you will get notifications for your default branch (i.e. main). However, you can choose to filter on a specific branch, or a pattern of branches or all branches.

/github subscribe org/repo commits for commit notifications from a default branch.
/github subscribe org/repo commits:* for commit notifications across all the branches.
/github subscribe org/repo commits:myBranch for commit notifications from a specific branch.
/github subscribe org/repo commits:users/* for commit notifications from a pattern of branches.

You can unsubscribe from commits feature using /github unsubscribe org/repo commits.

Note: Previously, you might have used commits:all to represent all branches. 'all' is no longer a reserved keyword. Going forward, you need to use '*' to represent all branches. If you have already configured with 'commits:all' previously, dont worry, it will continue to work until you update the commits configuration.

Label filters for prs and issues

Label filters allow filtering incoming events based on a allow list of required labels.

This is an overview of the event types that are affected by the required-label filter.

| Event | Is filtered | | ---------------------- | ----------------- | | Pull | ✅ Yes | | Comment (PR and Issue) | ✅ Yes | | Issue | ✅ Yes | | Review | ✅ Yes | | Commit/Push | ❌ No | | Branch | ❌ No |

Creating a filter

Create a filter with:

/github subscribe owner/repo +label:"priority:HIGH"

This creates a required-label filter with the value priority:HIGH. Incoming events that support filters are discarded unless they have that label.

Updating a filter

To update the existing filter just enter a new one, the old one will be updated. Currently, we only support having one filter. Multiple filters might be supported in the future.

/github subscribe owner/repo +label:"teams/designers"

Now the existing filter priority:HIGH has been replaced by teams/designers.

Removing filters

Removing a filter is available via unsubscribe

/github unsubscribe owner/repo +label:teams/designers

This removes the teams/designers filter.

Listing filters

To see the currently active filters use

/github subscribe list features

Valid filters

It is common to have certain special characters in labels. Therefo

Slack

Install / Use

README