Skip to main content

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:

a single message notifying that a PR was opened, with further discussion in the thread

Then, notifications for a given pull request are all done in a thread:

a thread for PR notifications, including requests for changes, a new revision, approval, and merging

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​

The installation has three main steps:

  1. Build and deploy the application
  2. Configure GitHub to send notifiactions to our bot
  3. Configure Slack to add our bot

Building and deploying the application​

  1. To start, check out the Slack Notifier repository and install its npm packages:

    git clone [email protected]:klothoplatform/slack-notifier.git
    cd slack-notifier

  2. Compile the application and run Klotho on it:

    npm run klotho

  3. Configure 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.)

    npm run pulumi config set aws:region us-west-2

    When Pulumi asks you whether to create the stack, say yes.

  4. Deploy the application:

    npm run pulumi up

    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:

npm run pulumi stack output

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.

  1. Navigate to the organization or repository.

  2. Click the "⚙️ Settings" link in the top banner.

  3. Select the Webhooks link in the left panel and click "Add webhook" button at the top-right.

  4. Enter the following data:

    FieldValue
    Payload URLPaste 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 typeapplication/json
    SecretLeave blank
    "Active" checkboxLeave checked
    "Which events...""Let me select individual events," and then select:
    • Issue comments
    • Pull request review comments
    • Pull request reviews
    • Pull requests
    Note: "Pushes" is selected by default; un-select it.

    Scroll to the bottom of the page, click "Add webhook", and that's it.

Configuring Slack​

  1. 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.

  2. 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 the request_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".

  3. Click the green "Install to Workspace" button to install the app.

  4. Slack auto-generated some security tokens, so we need to deploy these to our deployed application.

    1. 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).

    2. 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.

  5. Redeploy the Klotho application:

    npm run pulumi up

    You should see two new aws:secretsmanager:SecretVersion resources. Select "yes" to perform the update.

  6. 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:

  1. Delete the Slack bot:

    1. Navigate to https://api.slack.com/apps/ and select the bot
    2. Scroll to the bottom of the page
    3. Click "Delete App"

  2. Delete the GitHub hook:

    1. In your web browser, open the organization or repository where you added the webhook
    2. Navigate to the "Webhooks" page
    3. Next to the webhook, click the "Delete" button

  3. Delete the Klotho application:

    1. cd to your slack repository

    2. run:

      npm run pulumi destroy

    3. Optionally, to delete Pulumi's history about the stack, run:

      npm run pulumi stack rm

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.