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
runsR 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
andcheck-r-package
now have aworking-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.