GitHub Actions for R developers, v2

We’re tickled pink to announce a v2 release of our collection of R related GitHub Actions at https://github.com/r-lib/actions.

If you are already using these actions, you might want to take look at the full list of changes first.

In this post, we’ll show how to set up r-lib/actions for your R package or project, and what is new in the v2 version.

About `rlib/actions`

GitHub Actions is a continuous integration service that allows you to automatically run code whenever you push to GitHub. If you’re developing a package this allows you to automate tasks like running R CMD check on multiple platforms or rebuilding your pkgdown website.

The r-lib/actions repo has a number of reusable actions that perform common R-related tasks: installing R and Rtools, pandoc, installing dependencies of R packages, running R CMD check, etc.:

setup-r installs R and on Windows Rtools,
setup-pandoc installs pandoc,
setup-r-dependencies installs R package dependencies,
check-r-package runs R CMD check on an R package.

See the README for the complete list of actions.

Setting up `r-lib/actions`

The r-lib/actions repo has example workflows, it is best to start with these.

You can copy the ones you’d like to use to the .github/workflows directory of your R package or project. For an R package you would typically want the test-coverage workflow and one of the check- workflows, depending on how thoroughly you want to check your package across operating systems and R versions. If your package has a pkgdown site then you probably also want the pkgdown workflow.

The usethis package has several helper functions to set up GitHub Actions for you: ?usethis::use_github_action. You’ll need the latest version of usethis, version 2.1.6 for this.

usethis::use_github_action("check-standard")
usethis::use_github_action("test-coverage")
usethis::use_github_action("pkgdown")

Which tag or branch should I use?

In short, use the v2 tag.

The v2 tag is a sliding tag. It is not fixed to a certain version, but we regularly update it with (non-breaking) improvements and fixes. If it is absolutely crucial that your workflow runs the same way, use one of the fixed tags, e.g. v2.2.2 is the most recent one.

As of today, usethis v2.1.6 defaults to configuring workflows from the v2 tag. But use_github_action() accepts a ref argument, which allows you specify a different tag (such as v2.2.2) or even a branch name or specific SHA.

What is new?

Make a plan and stick to it

setup-r-dependencies@v2 takes a more principled approach to resolving and installing system and package dependencies:

It looks up all system (on supported Linux distributions) and package dependencies, and works out an installation plan with a set of package versions that are compatible with each other. (If it cannot find such set, then the action already fails here.)
It writes the plan into a lock file. This is a machine readable (JSON) file, that it also printed to the job’s log file. This is the blueprint of the installation.
It potentially restores a cached set of installed packages. These are often the same exact package versions that are included in the installation plan. However, for efficiency, setup-r-dependencies also restores cache versions that are slightly different.
On Linux (if the distribution is supported) it installs all system requirements, according to the lock file.
It goes over the install plan again, to check that the packages (potentially) restored from the cache are the same as the ones in the plan. If a package is different, then it upgrades (or downgrades) it according to the plan.
At the end of the job, is saves the installed packages into the cache.

At the end of the installation you can be sure that exactly the planned packages are installed.

See the setup-r-dependencies README for more explanation and examples.

Simpler workflow files

If you update your existing workflows to use the v2 actions, also take a look at the new example workflows. These are typically much simpler than the previously suggested workflows, because we moved some workflow steps into the new actions. E.g. check-r-package always prints testthat output and it uploads the check directory as an artifact on failure, you don’t need to do these explicitly in the workflow. setup-r-dependencies now prints the session info with all installed packages, no need to do this explicitly.

To be clear, “updating your GHA workflows to v2” generally goes beyond just changing every instance of v1 to v2. The example workflows have also evolved, i.e. you really need to update entire YAML workflow file.

Snapshots as artifacts

Encoding issues are not uncommon in snapshot tests across platforms. To make these easier to debug, check-r-package@v2 will now upload snapshot output as artifacts if you set the upload-snapshots parameter to true:

      - uses: r-lib/actions/check-r-package@v2
        with:
          upload-snapshots: true

See the Snapshot tests article in the testthat manual for more about testthat snapshots.

Rtools42 support

Rtools42 is the new version of the Rtools compiler bundle, which will be the default for latest R 4.2.0. You can now optionally install Rtools42 with the setup-r action. By default setup-r uses Rtools40 because it is pre-installed on the CI machines, and it is fully compatible with Rtools42. To select Rtools42, set the rtools-version parameter to 42:

      - uses: r-lib/actions/setup-r@v2-branch
        with:
          r-version: 'devel'
          rtools-version: '42'

See this example if you want to use rtools-version in a matrix build.

Other changes

See the READMEs for more details.

setup-r-dependencies now does not always install the latest versions of the dependencies.
You can ask setup-r-dependencies to ignore some optional dependencies on older R versions.
The Linux system requirements look-up is more robust now, and uses SystemRequirements fields from all local, GitHub or URL remotes, and it also uses the package installation plan, instead of only relying on the dependency tress of CRAN packages.
setup-r-dependencies and check-r-package now have a working-directory parameter.
setup-r-dependencies now works on all x86_64 Linux distributions (but only installs system requirements on supported ones, see the README).
The example *down (blogdown, pkgdown and bookdown) workflows now build the web site in pull requests as well, but only deploy on push and release events. They also have a manual trigger.
The example *down workflows now protect against race conditions.

Feedback

Your feedback is much appreciated. Before reporting a new issue, please check if it was already reported, see the list of issues, especially the pinned issues (if any) at the top of the issue page.

Acknowledgements

Thanks to everyone who contributed to r-lib/actions: @andrewl776, @arisp99, @assignUser, @astamm, @bribroder, @duckmayr, @hadley, @harupy, @ijlyttle, @IndrajeetPatil, @jeroen, @krlmlr, @lorenzwalthert, @MichaelChirico, @MikkoVihtakari, @ms609, @pat-s, @s-u, @slwu89, @vincentarelbundock, and @yutannihilation.