R + GitHub Actions - A love story

This repo is not maintained after May 11, 2021 and may become out of date.

Demo

• Hello world - echo 'hello world!'
• Code Linting hello world - Minimal steps to call lintr::lint_package()
• Bare bones - Check R package - Minimal steps to execute R CMD check .
• Regular - Check R package - Full R cmd check using pak.

Usage

To add the workflow files to your R package repo, call:

## Typical R package repos
# usethis::use_github_action_check_standard()

# This R package repo uses (and all future repos should use)
usethis::use_github_action("check-pak")
usethis::use_github_action("pkgdown-pak")

… then git commit and git push the changes in your local repo!

GitHub Actions

• GitHub’s answer to CI

• Automate, customize, and execute your software development workflows right in your repository with GitHub Actions. You can discover, create, and share actions to perform any job you’d like, including CI/CD, and combine actions in a completely customized workflow.

• Virtual environments
  • Ubuntu 18, 20
  • macOS 10.15, 11
  • Windows Server 2016, 2019
• Usage Limits
• Links:
  • Main: https://docs.github.com/en/actions
  • Intro: https://docs.github.com/en/actions/learn-github-actions/introduction-to-github-actions
  • Syntax: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
• “I’d bet almost everything you can do in Jenkins, you can do in GitHub Actions” - Derrick
  • See example of executing all steps within a Docker container.

Story

When submitting packages to CRAN, it helps to let them know where you’ve tested R packages and on which platforms. The more platforms and R versions that you can test your package on, the better!

History

Before GitHub Actions, developers used Travis-CI (and some packages still do!). However, Travis was limited in that it could only test using a single type linux machine. You could test on multiple R versions.

Given authors develop on a mac, this required package authors to use r-hub (lead by Gabor) to test on different flavors of windows machines. This service was MUCH better the praying and hoping your code worked, but was still not very robust.

R-hub may still be a good place to check if you have compiled ./src code. However, this is a small number of R packages.

CI Need

As RStudio has become more popular and usage demands are becoming more spread out, packages like plumber need to be sure they work on multiple operating systems and multiple versions of R.

To feel comfortable submitting a heavily used R package, I like to test on using:

• Operating Systems
  • macOS,
  • windows,
  • ubuntu 16, and
  • ubuntu 20
• R versions
  • devel
  • release
  • oldrelease
  • 3.4
  • 3.3 (As there is no name called reallyoldrelease)

tidyverse supports the latest 4 versions of R

These combinations create a large test matrix and is not fun to manually execute.

CI Solution

GitHub Actions (GHA) for R was initially explored by Max Held during his summer internship at RStudio. Since then, GHA created a complete different interface and Max’s work was repurposed in https://github.com/r-lib/actions by Jim Hester.

Using r-lib/actions allows package developers to use consistent routines, yet customize the CI execution.

Two useful steps:

• r-lib/actions/setup-r@v1: Set up the R process. Example
• r-lib/actions/setup-pandoc@v1: Set up pandoc. Example

This repo uses pak to install system requirements and install all package dependencies. To me, any general usage of remotes should be replaced with pak. It is better for many reasons. Two being:

• wholistic installation (consistency): It knows everything that is going to be installed before installing the first package.

• parallel installation (speed): If two packages are not dependent on each other, they may be install in parallel.

• pak

  • A new version of remotes

  • A fresh approach to package installation

  • Website: https://pak.r-lib.org/
  • GitHub: https://github.com/r-lib/pak

Real Life Usage

• r-lib/actions
  • Examples: https://github.com/r-lib/actions/tree/master/examples
    • Run code within a Docker image: examples/docker.yaml
• plumber R package
  • R CMD check: .github/workflows/R-CMD-check.yaml
    • Checks package on many different combinations of OS and R version
  • Build and deploy a Docker file: .github/workflows/docker.yaml
    • Builds and deploys plumber’s Docker file to dockerhub
  • Build and deploy a pkgdown website: .github/workflows/pkgdown.yaml
    • Automatically pushes latest changes to gh-pages branch.
  • Test coverage: .github/workflows/test-coverage.yaml
    • Execute test coverage (basically testing all code) on a single operating system and R version. This workflow uploads test coverage to codecov.
  • PR commands: .github/workflows/pr-commands.yaml
    • Listens to comments and conditionally adds the results of devtools::document() to the same PR.

Test coverage and PR commands could be combined into a single workflow, such as rstudio/shiny’s Rituals.

• shiny R package
  • Rituals: .github/workflows/rituals.yaml
    • Performs many rituals within a single GHA workflow
      • Pulls from push branch or PR branch
      • Conditionally checks for bad urls (on release only)
      • devtools::document()
      • Builds all JavaScript code
      • Pushes back to the push branch or PR branch
• bslib R package
  • Rituals
    • Build Readme.md
• pak R package
  • Repository Dispatch:
    • build.yaml has many “dispatch” commands to pak-build event.
    • Executes build-package.yaml workflow via pak-build event
• shinycoreci-apps repo
  • Shiny apps
    • Long running GHA execution
    • Executes on 4 R versions and 3 operating systems
    • Checks 200+ Shiny applications
    • Regular user recommendations
  • Deploy to Connect & shinyapps.io
  • Deploy SSO & SSP docker files for testing
  • Remove stale GitHub Branches in repo