GitHub Actions for R developers, v2
This article is originally published at https://www.tidyverse.org/blog/
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
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
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-rinstalls R and on Windows Rtools,
setup-r-dependenciesinstalls R package dependencies,
R CMD checkon an R package.
See the README for the complete list of actions.
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
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.
In short, use 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.
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-dependenciesalso 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.
README for more explanation and examples.
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
v2. The example workflows have also evolved, i.e. you really need to update entire YAML workflow file.
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
- uses: r-lib/actions/check-r-package@v2
See the Snapshot tests article in the testthat manual for more about testthat snapshots.
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
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
- uses: r-lib/actions/setup-r@v2-branch
this example if you want to use
rtools-version in a matrix build.
See the READMEs for more details.
setup-r-dependenciesnow does not always install the latest versions of the dependencies.
You can ask
setup-r-dependenciesto ignore some optional dependencies on older R versions.
The Linux system requirements look-up is more robust now, and uses
SystemRequirementsfields 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.
check-r-packagenow have a
setup-r-dependenciesnow 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.
Thanks to everyone who contributed to
Please visit source website for post related comments.