Installing our Slack Notifier for Github
Like many development teams, we here at Klotho use both GitHub and Slack for our daily work. And like many development teams, we like to get Slack notifiactions for GitHub pull requests. GitHub has an integration bot for that, but we didn't love it — so we wrote our own and open-sourced it. This tutorial will explain what our bot does and how you can install it.
What's the Klotho Slack Notifier for GitHub, and how is it different?
GitHub's built-in integration for Slack is noisy: notifications all go to the channel as top-level messages, which can overwhelm any other discussion in it. Just as bad, the flat organization makes it hard to track any particular pull request. We tried to solve the noisiness issue by putting all of the notifications in a separate channel, which we then ignored. Instead, people would manually post their pull requests to our main chat. If only a computer could do that for us!
Our notifier uses Slack threads, so the main channel has minimal noise:
Then, notifications for a given pull request are all done in a thread:
This notifier is a real-world application; we use it every day, and are constantly improving it. And, of course, it's built with Klotho!
Installing Klotho's Slack Notifier for GitHub
Prerequisites
- Klotho CLI installed
- Node.js 16.x+ (& NPM)
- Docker
- AWS credentials configured using environment variables (see Pulumi's documentation for AWS access):
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
; orAWS_PROFILE
The installation has three main steps:
- Build and deploy the application
- Configure GitHub to send notifiactions to our bot
- Configure Slack to add our bot
Building and deploying the application
To start, check out the Slack Notifier repository and install its npm packages:
git clone [email protected]:klothoplatform/slack-notifier.git
cd slack-notifierCompile the application and run Klotho on it:
- Shorthand
- Under the hood
npm run klotho
npm install # Only needed the first time you build
npx tsc
klotho dist --app klotho-slack-notifier-bot --provider aws # You can name the app whatever you like
npm --prefix compiled install # Install Pulumi's requirementsConfigure Pulumi to tell it the AWS region you'd like to deploy to. We're using us-west-2, but you can use whatever region you like. (For more details, see our general deploying guide.)
- Shorthand
- Under the hood
npm run pulumi config set aws:region us-west-2
pulumi config set aws:region us-west-2 --cwd compiled --stack klotho-slack-notifier-bot
When Pulumi asks you whether to create the stack, say yes.
Deploy the application:
- Shorthand
- Under the hood
npm run pulumi up
pulumi up --cwd compiled --stack klotho-slack-notifier-bot
Pulumi will show you a preview of what it's about to deploy, and ask you to confirm. The deployment may take a few minutes.
When the deploy completes, you'll see a URL for your new application's API Gateway endpoint. It should be something like:
https://abcde01234.execute-api.us-west-2.amazonaws.com/stage
You can always get this URL again later by running:
- Shorthand
- Under the hood
npm run pulumi stack output
pulumi stack output --cwd compiled --stack klotho-slack-notifier-bot
Now that we have our application deployed, we need to integrate it with GitHub and Slack.
Configuring GitHub
You can configure the GitHub integration at either an organization level or for a specific repository. If you configure it at the organization level, the application will get notifications for all PRs within that organization.
Navigate to the organization or repository.
Click the "⚙️ Settings" link in the top banner.
Select the Webhooks link in the left panel and click "Add webhook" button at the top-right.
Enter the following data:
Field Value Payload URL Paste the endpoint URL above, and add /github
to it. The full URL should look something like:https://abcde01234.execute-api.us-west-2.amazonaws.com/stage/github
Content type application/json Secret Leave blank "Active" checkbox Leave checked "Which events..." "Let me select individual events," and then select: - Issue comments
- Pull request review comments
- Pull request reviews
- Pull requests
Scroll to the bottom of the page, click "Add webhook", and that's it.
Configuring Slack
Navigate to https://api.slack.com/apps?new_app=1. Select "From an app manifest", and then select the workspace where you want the bot. Hit "next" to continue.
In the root of the slack-notifier repository, find the file named
slack-app-manifest.json
. Copy its contents, and paste them into the manifest dialogue in the Slack web page. Before you hit "next", update therequest_url
field in the manifest to your Klotho application endpoint's URL, followed by/slack
. It should look something like:https://abcde01234.execute-api.us-west-2.amazonaws.com/stage/slack
Now, hit "Next". You can review the app's settings, and then hit "Create".
Click the green "Install to Workspace" button to install the app.
Slack auto-generated some security tokens, so we need to deploy these to our deployed application.
Signing secret:
- Slack should have taken you to the "Basic Information" page; if not, navigate there using the left-hand panel.
- Scroll down to "Signing Secret"
- Click "Show"
- Copy the signing secret, and then paste it into a new file
compiled/slack_signing_secret
. Do not check this file in (it should be gitignored already).
Bot token:
- Navigate to the "OAuth & Permissions" page in the left-hand panel of the Slack app page.
- Find the "Bot User OAuth Token"
- Copy the token and paste it into a new file
compiled/slack_token
. As before, do not check this file in.
Redeploy the Klotho application:
- Shorthand
- Under the hood
npm run pulumi up
pulumi up --cwd compiled --stack klotho-slack-notifier-bot
You should see two new
aws:secretsmanager:SecretVersion
resources. Select "yes" to perform the update.Go to the "Event Subscriptions" page in the left-hand panel of the Slack app page. You should see a warning that your request URL didn't respond; hit "retry", and it should now succeed.
The bot is ready to go!
Using the bot
Invite your new bot to a channel
In Slack (the actual chat application, not the administration page), go to the channel where you want notifications. Type /add
and select "add apps to this channel". Select KlothoBot, and the bot will join the channel. Any new PR will get notifications; the bot will not backfill existing open PRs.
KlothoBot works with both public and private channels.
Uninstalling
To remove KlothoBot from a specific channel, go to that channel in Slack and type:
/remove @KlothoBot
To delete the bot entirely:
Delete the Slack bot:
- Navigate to https://api.slack.com/apps/ and select the bot
- Scroll to the bottom of the page
- Click "Delete App"
Delete the GitHub hook:
- In your web browser, open the organization or repository where you added the webhook
- Navigate to the "Webhooks" page
- Next to the webhook, click the "Delete" button
Delete the Klotho application:
cd
to your slack repositoryrun:
- Shorthand
- Under the hood
npm run pulumi destroy
pulumi destroy --cwd compiled --stack klotho-slack-notifier-bot
Optionally, to delete Pulumi's history about the stack, run:
- Shorthand
- Under the hood
npm run pulumi stack rm
pulumi stack rm --cwd compiled
Customizing the Slack app
You can make various cosmetic changes to the Slack app from its administration page (https://api.slack.com/apps, then select your app).
In the "Basic Information" page, scroll down to change the app name, description, icon, or background color.
In the "App Home" page, you can edit the "App Display Name" to change the bot's display name or @username.
For anything more interesting than that, we'll need a code change. Hop on over to klothoplatform/slack-notifier on GitHub and contribute! We welcome pull requests or issues.