GitHub Actions are a powerful way to automatically launch workflows every time you push changes to a GitHub repository. This is a form of Continuous Integration (CI), which helps ensure that your code is always working as expected (without having to manually check each time).
Here, we have designed a robust, reusable, and flexible action
specifically for the development of R packages. We also provide an R
function to automatically generate a workflow file that calls the
rworkflows
composite action:
Currently, rworkflows
action performs the following tasks:
- Builds a Docker container to run subsequent steps within.
- Builds and checks your R package (with CRAN and/or Bioconductor checks).
- Runs unit tests.
- Runs code coverage tests and uploads the results to Codecov.
- (Re)builds and launches a documentation website for your R package.
- Pushes an Rstudio Docker container to DockerHub with your R package and all its dependencies pre-installed.
Importantly, this workflow is designed to work with any R package
out-of-the-box. This means you won’t have to manually edit any yaml
files, just run the rworkflows::use_workflow()
function and you’re
ready to go!
Note:
rworkflows
uses, was inspired by, and benefits from the work of many other projects, especially:
biocthis
,usethis
,actions/
,r-lib/actions
,bioc-actions
,JamesIves/github-pages-deploy-action
,docker/build-push-action
,bioconductor_docker
. For more details on how these projects relate torworkflows
, please see below.
Install and create the workflow in your R package’s project folder.
## in R
#### Install rworkflows R package ####
### For the stable CRAN release
if(!require("rworkflows")) install.packages("rworkflows")
### Or, for the latest development version
# if(!require("rworkflows")) remotes::install_github("neurogenomics/rworkflows")
### Create workflow file
path <- rworkflows::use_workflow()
Push to GitHub, and let everything else run automatically! You can check the status of your workflow by clicking on the Actions tab in your GitHub repo.
## in the Terminal
git add .
git commit -m "Added rworkflows"
git push
Note: If you want to skip running GitHub Actions on a particular
push, simply add “[skip ci]” somewhere in the commit message, e.g.:
git commit -m "Update README [skip ci]"
Introductory vignette for using rworkflows
.
Copy-and-paste instructions for creating a Docker or Singularity
container with the rworkflows
R package pre-installed.
Interactive graph showing all the GitHub repos that currently use the
rworkflows
action.
Talk on the background, motivation, and utility of rworkflows
.
Step-by-step tutorial showing how to use rworkflows
in an R package.
To use certain features of rworkflows
, you may need to set up one or
more GitHub
Secrets:
PAT_GITHUB
[Optional]: Can grant access to private repos on GitHub Actions. You can generate your very own Personal Authentication Token withusethis::create_github_token()
. See the GitHub docs for details.DOCKER_TOKEN
[Optional]: Allows GitHub Actions to push to a DockerHub account.
If you use rworkflows
, please cite:
Brian M. Schilder, Alan E. Murphy, & Nathan G. Skene (2023) The rworkflows suite: automated continuous integration for quality checking, documentation website creation, and containerised deployment of R packages, Research Square; https://doi.org/10.21203/rs.3.rs-2399015/v1
rworkflows
builds upon the work of many others, especially the
following:
This workflow is largely inspired by the workflow generated by the
use_bioc_github_action()
function within the
biothis
package, developed by @lcolladotor.
- Uses dynamic variables to specify R/Bioconductor versions
(e.g.
r: "latest"
) and the name of your R package, as opposed to static names that are likely to become outdated (e.g.r: "4.0.1"
). - Additional error handling and dependencies checks.
- Re-renders
README.Rmd
before rebuilding the documentation website.
biocthis
was in turn inspired by usethis
.
A general set of GitHub Actions maintained by the core GitHub team.
A set of GitHub Actions for R development maintained by the Rstudio/Posit team.
Bioconductor-oriented GitHub Actions created by @grimbough.
Builds and deploys the GitHub Pages documentation website in the
rworkflows
GHA workflows.
A set of GitHub Actions for building/pushing Docker containers.
Uses the official
bioconductor/bioconductor_docker
Docker container.
NOTE: Whenever a new version of Bioconductor is released, the
bioconductor/bioconductor_docker
container will often lag behind the
actual Bioconductor releases for up to several days, due to the time it
takes to update the container. This means that sometimes “devel” in
Bioconductor/bioconductor_docker
is actually referring to the current
“release” version of Bioconductor (i.e. the previous Bioc version’s
“devel”). For further details, see this
Issue,
and the Bioconductor release
schedule.
This Dockerfile was partly adapted from the scFlow Dockerfile. Unlike other Dockerfiles, this one does not require any manual editing when applying to different R packages. This means that users who are unfamiliar with Docker do not have to troubleshoot making this file correctly. It also means that it will continue to work even if your R package dependencies change.
A very useful command line tool for testing GitHub Actions locally.
utils::sessionInfo()
## R version 4.2.1 (2022-06-23)
## Platform: x86_64-apple-darwin17.0 (64-bit)
## Running under: macOS Big Sur ... 10.16
##
## Matrix products: default
## BLAS: /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRlapack.dylib
##
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## loaded via a namespace (and not attached):
## [1] here_1.0.1 rprojroot_2.0.3 digest_0.6.31
## [4] utf8_1.2.3 BiocFileCache_2.6.1 R6_2.5.1
## [7] stats4_4.2.1 RSQLite_2.3.1 evaluate_0.21
## [10] httr_1.4.6 ggplot2_3.4.2 pillar_1.9.0
## [13] yulab.utils_0.0.6 rworkflows_0.99.13 biocViews_1.66.3
## [16] rlang_1.1.1 curl_5.0.0 data.table_1.14.8
## [19] rstudioapi_0.14 whisker_0.4.1 blob_1.2.4
## [22] DT_0.28 RUnit_0.4.32 rmarkdown_2.22
## [25] desc_1.4.2 readr_2.1.4 stringr_1.5.0
## [28] htmlwidgets_1.6.2 dlstats_0.1.7 BiocPkgTools_1.16.1
## [31] igraph_1.5.0.1 RCurl_1.98-1.12 bit_4.0.5
## [34] munsell_0.5.0 compiler_4.2.1 xfun_0.39
## [37] pkgconfig_2.0.3 BiocGenerics_0.44.0 rorcid_0.7.0
## [40] htmltools_0.5.5 tidyselect_1.2.0 tibble_3.2.1
## [43] httpcode_0.3.0 XML_3.99-0.14 fansi_1.0.4
## [46] dplyr_1.1.2 tzdb_0.4.0 dbplyr_2.3.2
## [49] bitops_1.0-7 rappdirs_0.3.3 crul_1.4.0
## [52] grid_4.2.1 RBGL_1.74.0 jsonlite_1.8.4
## [55] gtable_0.3.3 lifecycle_1.0.3 DBI_1.1.3
## [58] magrittr_2.0.3 scales_1.2.1 graph_1.76.0
## [61] cli_3.6.1 stringi_1.7.12 cachem_1.0.8
## [64] renv_0.17.3 fauxpas_0.5.2 xml2_1.3.4
## [67] rvcheck_0.2.1 filelock_1.0.2 generics_0.1.3
## [70] vctrs_0.6.2 gh_1.4.0 RColorBrewer_1.1-3
## [73] tools_4.2.1 bit64_4.0.5 Biobase_2.58.0
## [76] glue_1.6.2 hms_1.1.3 fastmap_1.1.1
## [79] yaml_2.3.7 colorspace_2.1-0 BiocManager_1.30.20
## [82] rvest_1.0.3 memoise_2.0.1 badger_0.2.3
## [85] knitr_1.43