For many teams, especially distributed teams, chat is a powerful way for members of the team to collaborate and coordinate their efforts. Chat in this context does not refer to sipping tea on a porch talking about how their day went. Chat refers to text-based tools, such as Slack, used by teams to communicate both synchronously and asynchronously.
Many teams find it helpful to have GitHub post important notifications into a chat room so teams are kept apprised of what’s going on with a repository. In this section, we set up a GitHub integration with one popular chat software, Slack.
Before you install the integration, you need to be the admin of a Slack workspace. You can create a free Slack workspace at https://slack.com.
After you set up your Slack workspace, installing the GitHub for Slack integration requires two key steps:
- Install the GitHub app for Slack in the Slack workspace.
- Add the Slack App for GitHub to your GitHub account.
The following sections cover these steps in detail.
1. Installing the GitHub app for Slack
To install the GitHub app for Slack:
- Go to https://slack.github.com and click the Add to Slack button in the center of the browser window.
If you’re not logged into your Slack workspace in the browser, clicking the Add to Slack button prompts you to sign into your slack workspace. Likewise, if you’re not logged into GitHub, the site prompts you to log into GitHub. When you’re authenticated to both, you see a Slack confirmation screen with information on what permissions the GitHub app will have to your Slack workspace. Figure 12-1 shows the confirmation screen with every section expanded (they’re collapsed by default), so you can see everything the integration can do.
Be sure you’re adding the GitHub app to the correct Slack workspace. If the wrong workspace is shown, you can change it by clicking the workspace drop-down list on the top right of this screen. Here, you can choose to change which Slack workplace you want to install the integration into. If the workspace isn’t listed there, you can click Sign in to another workspace.
- Click Continue to go to the GitHub app configuration screen.
As shown in Figure 12-2, this screen prompts you to pick which channels this app should be available to.
- Choose All Public Channels.
Any public channel in your Slack workspace can choose to make use of this app and subscribe to GitHub repository notifications.
- Click the Install button to complete the installation on the Slack side.
You’re redirected back to Slack.
If you have the Slack desktop application, clicking the Install button attempts to launch the application and take you to the workspace where you installed the app. If you haven’t yet added the workspace to the desktop application, you’ll just be in the last workspace you used. This can be a bit confusing as it may seem like the installation didn’t work. Don’t worry, it probably did work. Just add the workspace to your desktop application and continue.
2. Subscribing to a repository in a Slack channel
After you install the GitHub app for Slack, you can subscribe to notifications for a GitHub repository from within a Slack channel:
- Type the following command:
/github subscribe owner/repository
For example, to subscribe to the repository we created for the readers of this book, https://github.com/thewecanzone/GitHubForDummiesReaders, you would type the following in a Slack channel:
/github subscribe TheWecanZone/GitHubForDummiesReaders
The first time you run this command, Slack prompts you to connect your Slack account to your GitHub account. as shown in Figure 12-3. This Slackbot message is visible only to you.
- Click the Connect GitHub Account button to start the process of connecting your account.
If you’ve already authenticated and authorized Slack on GitHub.com by either doing these steps previously or by following the steps in the section “Installing the GitHub app for Slack,” earlier in this chapter, your browser will open and automatically authenticate and redirect you to Slack.
If you’re not authenticated on GitHub.com, GitHub prompts you to authenticate first and complete the rest of the steps in this section.
After authenticating, GitHub prompts you to authorize the Slack app, as shown in Figure 12-4. You won’t need to do this again when installing GitHub into other Slack workspaces.
- Click Authorize Slack by GitHub to continue.
After you authorize the app, GitHub prompts you to choose an org to install the app into or to choose your account.
- Click the account name corresponding to the repository you want to subscribe to.
In this example, we are installing to a repository in TheWeCanZone org, so we would click that option. Clicking the account takes you to next step where you specify which repositories the app may access, as shown in Figure 12-5.
- Choose All repositories to enable the app for all current and future repositories or click Only select repositories and pick the specific repositories that may use the app.
- After you select the set of repositories, click the Install button to complete the installation on GitHub.
Slack is now listed in the Applications page of your account or organization settings. You can go there to change the settings for the app or to uninstall it.
3. Trying out the GitHub Slack integration
With the installation complete, you can now subscribe to GitHub repositories in your Slack channels. To see the full list of Slack commands, type the following:
/github help
The output of this command is shown in Figure 12-6.
To test the GitHub app and open a new issue:
- Run the following command.
/github open TheWeCanZone/GitHubForDummiesReaders
A Slack dialog box appears. You can use this dialog box to create a new issue, as shown in Figure 12-7.
- Fill in the dialog box and click the Open button.
Clicking the Open button creates the issue on GitHub. And because we’re subscribed to that repository, we get a Slack message in the channel that the issue was created as shown in Figure 12-8.
If you find a bug with the GitHub integration or have an idea for a way it could be better, good news! It’s open source on, of course, GitHub! You can log issues or even contribute at https://github.com/integrations/slack.
The /github subscribe command by default subscribes a channel to notifications for the following features of a repository:
» issues: Opened or closed issues
» pulls: New or merged pull requests
» statuses: Statuses on pull requests
» commits: New commits on the default branch (usuallymaster)
» deployments: Updated status on deployments
» public: A repository switching from private to public
» releases: Published releases
To subscribe to only a single feature, use the /github subscribe owner/repo [feature] command.
/github subscribe TheWeCanZone/GitHubForDummiesReaders reviews
You can remove a single feature by using the /github unsubscribe owner/repo [feature] command. For example, to remove commit notifications on the default branch, run the following command.
/github unsubscribe TheWeCanZone/GitHubForDummiesReaders commits
Additional features are disabled by default:
» reviews: Pull request reviews
» comments: New comments on issues and pull requests
» branches: Created or deleted branches
» commits:all: All commits pushed to any branch
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.