Custom Slack Notifications with Atomist Event Handlers

Part 2 of 2

Canned Slack notifications are useful, but what if you want to do something more, like tailor messages for you and your team? You might want your bot to react to GitHub pushes, updates to issues, pull requests, or similar events.

In about 10 minutes, you can teach the Atomist bot to respond to specific commit messages on GitHub. You’ll then have a working bot that you can modify however you want.

Part 1 of this series showed how to add a function to your Slack bot using a command handler. This post introduces event handlers, which are TypeScript functions that define how your bot responds to changes in the outside world.

Let’s do this.

Step 0: Add Bot

If you already added the Atomist bot to your Slack team in the previous post then you can skip this step; otherwise click the button below.

Step 1: Generate Sample Project

The bot provides a project template that creates a GitHub repo with all the code you need for this example. In Slack, type @atomist generate event-handler-sample:

Step 2: Start Listening

This isn’t much of an event handler without events to react to. Let’s fix that.

In Slack, run the command @atomist install github webhook

This configures a repository webhook on the GitHub repo you just created. The bot is now listening for activity on that repo only.

Select the issue-crusher repo that you just created.

As soon as the webhook is installed, the bot offers a couple of options for “linking” your newly created repo to a Slack channel. This tells the bot where you want it to send messages about commits, issues, and PRs in that repository — usually a channel where you discuss the project with your team.

For this example, you have to click the “Go ahead” button, which links your generated repository with a newly created Slack channel called #issue-crusher. In the next step, you will see details of how this link is used to address bot messages.

Step 3: Inspect and Run the Event Handler

Now it’s time to clone the repository containing the sample event handler.

$ git clone git@github.com:YOUR_GITHUB_USER/issue-crusher.git
$ cd issue-crusher

The two most important parts of the event handler code are the event subscription and the handle function that fires each time an event matching the subscription occurs:

GraphQL is used to define the event subscription. We’re really excited about this! GraphQL gives developers some fantastic advantages:

• amazing tooling support such as tab completion for building and testing new subscriptions
• queryable, self-describing schema
• relationships across types when events come from different source systems, for example, commits — builds — containers — pods
• automatic schema evolution as new event types are added
• payload aliasing
• type safety, when used with TypeScript

The GraphQL subscription you see above subscribes to all new commits, and requests that the payload contain the sha, the commit message, and the repo. Plus, this really is a “graph”. Besides the commit data, the subscription also requests that any channels linked to the repo be returned. (Remember when you clicked the “Go ahead” button above? That’s where you linked your repo and your Slack channel).

Run the event handler and make sure you can see your Slack Bot respond when you make a new commit.

$ npm install && \
  npm run compile && \
  $(npm bin)/atomist-config && \
  npm run autostart

If you’re running an Atomist automation for the first time, the $(npm bin)/atomist-config command asks for your Slack team-id and requests that you log in to GitHub to create a personal access token:

You can get your Slack team-id from your bot using the command @atomist team.

Step 4: Trigger the Bot

Trigger the handler by pushing a commit. Here’s one way to do that:

$ echo "change" >> README.md && \
  git add -A && \
  git commit -am "crushed #1" && \
  git push origin master

Your bot notices this commit and sends you a message:

Your event handler is responsible for that message!

Step 5: Change it

You can change the handler and then trigger it by pushing a new commit. Since you started the event handler in autostart mode, you don’t even have to restart anything.

The message pattern you’re using is on line 42. Just change that line to search for other patterns in the commit message.

const Pattern = /[cC]rush(ed|ing)[\s]*#([0-9]*)/g;

The bot message is constructed on line 58. You can easily alter the text by modifying the first parameter of the addressChannels function call:

Next Steps

You’ve now laid the groundwork for using event handlers to embed commands in Slack bot messages. In the next post you’ll tie these concepts together and create a bot automation capturing real GitHub events and turning them into interactive buttons. This is an important step towards making your events actionable, and it is where your bot starts to do way more than just notify!