In r-lib/ghactions: GitHub actions for R

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)

Continuous integration and delivery (CI/CD) have evolved as software development best practices, and they also strengthen reproducibility in (data) science. By programmatically triggering CI/CD, output versions (say, a PDF report or compiled binaries) are bound to a particular version (a git commit) of the source.

For widespread adoption of this best practice in the R community, CI/CD needs to be simple, fast, and easy to reason about if things go wrong.

GitHub actions is a new workflow automation feature of the popular code repository host GitHub.

Workflow Automation as Code

One of the great innovations in the CI/CD space in the past couple of years has been to express such development workflows as code. As such, it can be shared, versioned and tested.

This is most powerful, when common parts of such code can be factored out.

GitHub Actions offers only one way in which you can do that: You can use container or JavaScript actions to abstract away the complexity of the runs: field for a particular step in your workflow. That can be quite helpful, especially when you are interacting with external services or complicated architectures. Container actions, in addition, allow you to provide arbitrary computing environments (docker images) for a step, while a JavaScript action will use the underlying virtual machine.

What GitHub Actions does (currently) not let you do is factor out common patterns across steps, or even jobs. This is frequently the case for projects from the same language (here: R) or communities (here: tidyverse), who might all be relying on very similar, if not identical workflows.

Microsoft's Azure Pipelines has an elegant way to share such yaml-templates, even while passing down parameters, but GitHub Actions does not offer this (yet).

Instead, you get this package, which will provide you with hopefully sensible workflows.

However, because these aren't linked dynamically from your repos, there will be no easy way to update or maintain them.

Limitations

GitHub Actions does not currently offer caching; if your package has many dependencies, your build times might be quite long.

What This Package Doesn't Do

The ghactions package is quite limited, and deliberately so: GitHub actions already provides most of the things we might want, and in a cross-platform way:

• a succinct and human-readable text file representation (YAML) used to model code automation workflows,
• a convenient model and marketplace to share actions,
• and even some templates for frequently used projects.

This package does not intend to solve these problems again, nor to completely wrap GitHub Actions in R. It's really just a glorified collection of templates to get you started quickly.

If you need something more advanced, chances are you're going to want to edit your workflows yourself. It's quite easy to use, and we'll try to gather and share best practices in this repository.

Thanks

This package is also heavily modeled on, and indebted to the usethis package by Jenny Bryan and Hadley Wickham.

Related Work

There are plenty of other proven ways to run CI/CD for R. Many rely on R support on TravisCI, maintained by Jeroen Ooms and Jim Hester. The travis and tic packages make it easier to work with them. You can use AppVeyor's Windows-based system via the r-appveyor package.

For serious, cross-platform testing of packages, there's the r-hub project.

r-lib/ghactions documentation built on Dec. 15, 2020, 4:07 p.m.