GitHub Actions

GitHub Actions is a platform for automating workflows remotely. In short, you write a small YAML file in the .github/workflows/ subfolder of your repo, which contains instructions for the code you want to run and when to run it.³ I’ve written before about using GitHub Actions for continuous integration of R packages, for example.

An action can be triggered by an event, like a git push to your repo. You can also schedule it with a cron job, to run every hour, once a day, or whatever.

Here’s what the YAML file looks like for the londonmapbot action:

name: londonmapbot

on:
  schedule:
    - cron: '0,30 * * * *'

jobs:
  londonmapbot-post:
    runs-on: macOS-latest
    env:
      TWITTER_CONSUMER_API_KEY: ${{ secrets.TWITTER_CONSUMER_API_KEY }}
      TWITTER_CONSUMER_API_SECRET: ${{ secrets.TWITTER_CONSUMER_API_SECRET }}
      TWITTER_ACCESS_TOKEN: ${{ secrets.TWITTER_ACCESS_TOKEN }}
      TWITTER_ACCESS_TOKEN_SECRET: ${{ secrets.TWITTER_ACCESS_TOKEN_SECRET }}
      MAPBOX_PUBLIC_ACCESS_TOKEN: ${{ secrets.MAPBOX_PUBLIC_ACCESS_TOKEN }}
    steps:
      - uses: actions/checkout@v2
      - uses: r-lib/actions/setup-r@master
      - name: Install rtweet package
        run: Rscript -e 'install.packages("rtweet", dependencies = TRUE)'
      - name: Create and post tweet
        run: Rscript londonmapbot-tweet.R

It’s interpreted like so:

• this action is called ‘londonmapbot’
• run this code at :00 and :30 past each hour⁴
• the first (and only) job in this action is called londonmapbot-post
• start up a remote machine with the latest macOS operating system installed (this is where your code will be run)
• set some environmental variables, in this case keys that will be used to access the Twitter and Mapbox APIs (see the ‘Secrets’ section later in this post)
• the steps of the job are to:
  • use some pre-written code by GitHub to check out the repo
  • use some prewritten code from r-lib that sets up R
  • install the {rtweet} package and its dependencies
  • run the named R script from the repo

I would recommend changing your GitHub notification alerts once the bot is up and running, otherwise you’ll get a message every time the action executes. You can change this under Settings > Notifications > GitHub Actions, where you can uncheck the boxes under ‘Notifications for workflow runs on repositories set up with GitHub Actions’.

{rtweet}

The action runs an R script that generates content for a tweet and then posts it. This script makes use of the package {rtweet} by Mike Kearney, which lets you interact with the Twitter API with R functions.

You need a Twitter account, of course, and also to sign up as a Twitter developer to access the API.

As a developer, you can create ‘apps’ to obtain keys: private alphanumeric passcodes that grant you access to the API.

Typically, when working locally, you would either provide these keys as bare strings, or put them in your .Renviron file. With the latter, you can then use Sys.getenv() to call them from your .Renviron, which stops you exposing the raw keys in your code.

Below is an example of how you can use {rtweet} to post a tweet from R if you’ve added the keys to your .Renviron.

# Install the package from CRAN
install.packages("rtweet")

# Create a token containing your Twitter keys
rtweet::create_token(
  app = "londonmapbot",  # the name of the Twitter app
  consumer_key = Sys.getenv("TWITTER_CONSUMER_API_KEY"),
  consumer_secret = Sys.getenv("TWITTER_CONSUMER_API_SECRET"),
  access_token = Sys.getenv("TWITTER_ACCESS_TOKEN"),
  access_secret = Sys.getenv("TWITTER_ACCESS_TOKEN_SECRET")
)

# Example: post a tweet via the API
# The keys will are in your environment thanks to create_token()
rtweet::post_tweet(status = "This is a test tweet.")

This is basically what happens in the londonmapbot R script too. When writing an action, the keys aren’t fetched from your .Renviron file, however. Instead, you can encrypt them on GitHub and provide them in the env call of your action’s YAML file. See the ‘Secrets’ section below for more detail on this.

Mapbox

Mapbox is a company with services for mapping, geocoding and navigation, which developers can use for integrating into their apps for things like asset tracking, route optimisation or anything that requires a map interface for users.

Again, you’ll need to set up a Mapbox account to get a key for using the API. While the target audience is largely commercial, there appears to be a generous free allowance of 1250 requests per minute for the static image API.

You can then pass parameters to the Mapbox API via a URL. This is well explained in the Mapbox Documentation, which has an excellent ‘playground’ interface for you to test out your call.

You basically modify a particular URL string to ask the API for what you want. For example, you can ask for a 300x200 pixel satellite image of the coordinates of -0.1709 and 51.5065 with zoom level 12, which is Hyde Park:

https://api.mapbox.com/styles/v1/mapbox/satellite-v9/static/-0.1709,51.5065,12,0/300x200?access_token=YOUR_MAPBOX_ACCESS_TOKEN

Visiting the URL in your browser returns the requested image as a JPEG:

The Serpentine is so aptly named.

Of course, you’ll need to replace the access-token placeholder (YOUR_MAPBOX_ACCESS_TOKEN) in that URL with your own Mapbox key. Rather than provide this as a bare string, the londonmapbot R script calls it from the environment (like we saw in the {rtweet} code in the last section).

Here’s the code used by londonmapbot to fetch the satellite image from Mapbox:

# Generate random coordinates
lon <- round(runif(1, -0.5, 0.27), 4)
lat <- round(runif(1, 51.3, 51.7), 4)

# Build URL and fetch from Mapbox API
img_url <- paste0(
    "https://api.mapbox.com/styles/v1/mapbox/satellite-v9/static/",
    paste0(lon, ",", lat),
    ",15,0/600x400@2x?access_token=",
    Sys.getenv("MAPBOX_PUBLIC_ACCESS_TOKEN")
)

# Download the image to a temporary location
temp_file <- tempfile()
download.file(img_url, temp_file)

The code shows a paste0() statement that builds the URL with random latitude and longitude and the Mapbox key. The image from that URL is then downloaded into a temporary file, where it can be supplied to the media argument of rtweet::create_tweet() for posting to Twitter.