Set up R-CMD-check with a GitHub Actions workflow and notify Slack
By: Jasen Mackie
Tags: Rstats, Github Actions, Slackbot, Slack, Notifications

How to: for a future me

Introduction

If you work in software, you know all about Continuous Integration and Continuous Deployment (CI/CD) pipelines. These are best practices for shortening feedback loops between code changes and successful builds. GitHub Actions are a fairly new feature in GitHub, but is growing rapidly thanks in part to community involvement and the GitHub Marketplace. I am fortunate enough to contribute to several packages in the R ecosystem, and most packages use Travis-ci for their CI pipelines. If you store your project on GitHub, then the nice thing about using GitHub Actions for your pipelines is that the functionality already resides in the same system. There are a bunch of other reasons why you may choose GitHub Actions over Travis, some of which are covered in this talk by Jim Hester at rstudio::conf 2020.

Now, chances are that if you work in a technology or service organization that you also use Slack. Something we are trying with several projects related to the R organization’s participation in the prestigious Google Summer of Code program for 2021 is to use Slack for asynchronous communication. Slack has a range of integrations that can be built into your workflow. For example you can add Travis, GitHub, Zoom integrations etc. This makes for a productive experience from a single workspace whilst working in Slack. One of the things we are testing is adding a Slack bot app for notifying the relevant channels of build status updates whenever code is pushed or pull requests are submitted to the relevant code repositories in GitHub. The rest of this document is intended to be a step-by-step guide for how we got that done…so that i can refer to it in future and hopefully someone else reading this might benefit.

Its worth noting that there are really 2 workflows merged into one; a workflow to run an R-CMD-check and a workflow to notify Slack of the results. We will look at each part separately in the next 2 sections.

Part 1: R-CMD-check

The first workflow is running an R-CMD-check with a GitHub Actions workflow. You can refer to the Github Actions for the R community repo for more information, examples, additional resources etc. For our purposes, and the example below we merely used the YAML for “A simple CI workflow to check with the release version of R”, but changed the OS it runs on to Ubuntu.

Thanks to the contributors of that repo and the developers of the rcmdcheck package which makes this all possible.

You will likely want to add a status badge for your workflow to your project README. If so, you can refer to GitHub docs for “Adding a workflow status badge.”

Part 2: Slack Notification

At this point the GitHub Marketplace shines again. There are several Slack Notify options from the Marketplace which are open source, but i ended up going with Slack Notify Build. The documentation was helpful, but i still found myself getting stuck in places, hence this post for my own future reference if nothing else.

In order to get the integration working you first need to create a Slack app. This app will connect to your GitHub repo and hook into the status of your workflows. Creating a Slack app is really simple, requiring no code. You can go to https://api.slack.com/apps and create your Slack app “from scratch,” or at least that was the option i chose.

Then, you will need to create a Bot user. This is well documented in the Slack API docs here.

Next, you will need to install the app to your Slack Workspace. You can do this from the Settings menu for your app. Once that is done, you will need to enable a few features before you are done with configuring your new app in Slack. You will need to:

Activate Incoming Webhooks

Add the following OAuth scopes:

Bot Token Scopes

At this point you are pretty much done with any Slack setup and config. The only thing left to do is add the app to your respective channel with the command “/invite GitHub Action” or whatever the name of your Slack Bot app is. If you dont you will see a build error in GitHub Actions workflows like the below (after activating the workflow by adding the appropriate yaml file in the .github/workflows folder) which is quite helpful…

We will need to add the Slack bot token to our repo environment secrets in the Settings menu in GitHub (note: can only be done by repo owner) and add the channel ID to the YAML file. More on that in the next section.

.github/workflows/slack-notify-build.yml

For an example of a working yaml file, see my gist here. For more info regarding GitHub Actions workflow syntax please refer to their docs. For general YAML syntax docs, see the Learn YAML in Y Minutes website.

At this stage you will need to do 2 things:

Add the Slack Bot User OAuth Token to your GitHub repo secrets. The token is available under the “OAuth & Permissions” menu option under Features in your Slack app. For info about how to add a repo secret in GitHub, please refer to the docs. Make sure the name you give the token in the GitHub repo secrets is the name you use in the YAML file. The value of course is the token itself. And add the channel ID (see this accepted answer in this SO question for info on how to get that ID).

Conclusion

Assuming all the above steps have been carried out, you should receive notifications to your Slack channel of the workflow status for an R-CMD-check. The example YAML file stored on gist shows the config for combining an R-CMD-check and sending a status update to Slack in a single notification (a single notification is possible as the same message ID is used for each update).

I hope this is helpful. None of this would be possible without the contributions from the r-lib community and of course the contributors from Vox Media for the build status GitHub Action Slack notification code.