GitHub issues are a fantastic tool to help manage software projects. Whether your repository is public or private, issues provide a great way to track tasks, enhancements, and of course, bugs. But, as we all know, Slack, is Where Work Happens. So it would be great if we could bring some of the functionality of GitHub issues into Slack, where many people are spending a lot of their time anyway.
This guide will walk you through setting up an API on Standard Library that receives messages from GitHub, when issues are created or closed. Those messages then get sent to Slack, where people in the channel can stay up to date on what’s happening, or assign a maintainer to the issue.
If you’re not familiar with Standard Library, we’re a serverless platform that enables everyone to build, ship, and integrate scalable APIs in a matter of seconds. With the help of our online development environment, Code on Standard Library, you build and deploy right from your browser.
Step 1: Create a Slack App
Navigate to your Slack app dashboard, and click “Create New App” in the top-right corner of the screen. You should be redirected to a page labeled “Basic Information” shortly. On the left side of the screen, you’ll see “Incoming Webhooks” under the “Features” category.
Incoming webhooks are the easiest way to post messages into Slack, on a per channel basis. They give you a unique URL that can post messages on behalf of your bot into a specific channel. Outside of creating them, there is no authentication needed to post messages, so make sure you keep it a secret.
Enable incoming webhooks by clicking the toggle on the next screen. Scroll down to the section titled “Webhook URLs for Your Workspace” and click “Add New Webhook to Workspace”. Choose a channel and click “Authorize”.
Note the “Webhook URL”, because it will be needed in just a moment.
Step 2: Deploy the Issue Bot API
With Slack all squared away, open up Code on Standard Library. If you click that link, a template for the issue-bot API will automatically open. If not, navigate to the “Community API Sources” tab and search for “steve/issue-bot”. Open to the env.json file, and you’ll find three variables. Enter the Slack webhook URL from Step 1 into SLACK_WEBHOOK_URL under the dev section.
Now hit cmd/ctrl + R to deploy your API. You’ll be greeted with a “Parameter Error”, because your functions/__main__.js endpoint requires three parameters. The three parameters, action, issue and, repository, will be provided by GitHub (for more on those, check out these docs). Speaking of GitHub, you’ll want to take note of the “API Endpoint URL” for your API, which you’ll give to GitHub.
Step 3: Configure the GitHub Webhook
Head over to the GitHub repo that you want to forward issues from, and click the “Settings” tab on the far right of the screen. Once there, click the “Webhooks” section on the left side of the screen.
After clicking “Add webhook” in the top right, you’ll be prompted to fill out a form. For the first part, enter the “API Endpoint URL” from Step 2 as the “Payload URL”, and select “application/json” as the content type.
After scrolling down a bit, you can choose which events to forward to your webhook. Opt to select individual events, and make sure to check “Issues”.
Double check that the webhook is marked as “Active” and click “Add webhook”. Now to test it out: head over to your GitHub repo and open an issue!
The user, repository, and issue elements are all links that will open their respective pages in the browser. As it stands, your API is also configured to forward when an issue is closed. Go back to GitHub and close the issue you just opened.
Step 4: Assigning Issues
So now your team is up to date with the happenings of one of your repos. The next logical step would be assigning a maintainer to that issue, from Slack. In order to enable interactive messages in Slack, you need to go back to the app dashboard and navigate to the section titled “Interactive Components”, under the “Features” category. Once enabled you need to configure the “Request URL”. This will be the same as the “API Endpoint URL” from Step 2, but with /assign/ added to the end. This will be the API endpoint that gets hit when a user assigns a maintainer.
The final step in Slack is to enable dynamic content. This will let the bot pre-populate a drop-down with a list of people eligible to be assigned to an issue. Scroll to the bottom of the “Interactive Components” page, to a section titled “Message Menus”. As the “Options Load URL” enter the “API Endpoint URL” from Step 2, with /assign/list/ added to the end.
With interactive components set up, there is still some work to do on GitHub’s end. Assigning an issue to someone will require making an authenticated API call to GitHub, so you need to create an access token. Navigate to your profiles settings page and click on “Developer settings” in the bottom left corner. From there, you want to click the last option on the left side, “Personal access tokens”.
On the next page, click “Generate new token”. You’ll need to name the token, and give it a scope. The token needs repo access to assign issues, so select that.
Once created, copy the token and go back to Code on Standard Library. Copy the token, as well as the username associated with the token, into the env.json file under GITHUB_TOKEN and GITHUB_USERNAME.
Hit cmd/ctrl + R to redeploy your API. To test the new functionality create another issue, or better yet, go to your webhooks page for the repo and scroll down to “Recent Deliveries”. There you’ll see all the events that GitHub has sent out. Find the one generated when you opened your first issue and click “Redeliver”.
In just a moment you’ll see a new message in Slack, similar to the first but with a new drop-down.
The drop-down will be populated with the GitHub usernames of the possible assignees (i.e. accounts with push access). Pick one, and after a moment the message will update to reflect the change. And of course, your GitHub issues page will show the new assignee.
That’s All!
I hope this tutorial has been helpful in showing you how easy it is to get started with Standard Library. For other ideas on how to automate your workflow, combine various integrations, and more, you can check out more guides written by the team here. If you have a neat idea you’d like to share, reach out to me directly by e-mail: [email protected], or follow the Standard Library team and me on Twitter.
Steve Meyer is a recent graduate of Oberlin College and Software Engineer at Standard Library. When he’s not programming, you can find him baking bread, or playing Red Dead Redemption II.