If you use rworkflows, please cite:
Schilder, B.M., Murphy, A.E. & Skene, N.G. rworkflows: automating reproducible practices for the R community. Nat Commun 15, 149 (2024). https://doi.org/10.1038/s41467-023-44484-5
rworkflows is a suite of tools to make it easy for R
developers to implement reproducible best practices on GitHub.
It includes three main components:
1. templateR
template: a CRAN/Bioc-compatible
R package template that automatically generates essential documentation
using package metadata.
2. rworkflows
R package: a lightweight CRAN package to
automatically set up short, customisable workflows that trigger the
rworkflows action.
3. rworkflows
action: an open-source action available on the GitHub Actions
Marketplace.
rworkflows action
stepsGitHub 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/Deployment (CI/CD), 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 can
perform the following tasks (with options to enable/disable/modify each
step):
conda
environment.rworkflows::use_badges().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 within seconds!
Note:
rworkflowsuses, 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 pushNote: 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 with usethis::create_github_token().
See the GitHub
docs for details.DOCKER_TOKEN [Optional]: Allows GitHub Actions to push
to a DockerHub account.rworkflows builds upon the work of many others,
especially the following:
biocthisThis workflow is largely inspired by the workflow generated by the use_bioc_github_action()
function within the biothis
package, developed by @lcolladotor.
rworkflowsr: "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").README.Rmd before rebuilding the
documentation website.usethisbiocthis was in turn inspired by
usethis.
actions/A general set of GitHub Actions maintained by the core GitHub team.
r-lib/actionsA set of GitHub Actions for R development maintained by the Rstudio/Posit team.
bioc-actionsBioconductor-oriented GitHub Actions created by @grimbough.
JamesIves/github-pages-deploy-actionBuilds and deploys the GitHub Pages documentation
website in the rworkflows GHA workflows.
docker/build-push-actionA set of GitHub Actions for building/pushing Docker containers.
bioconductor_dockerUses 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.
scFlowThis 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.
actA very useful command line tool for testing GitHub Actions locally.
actions/runner-imagesRunner images for each OS provided by GitHub.
actions/setup-minicondaGitHub Action to setup Miniconda and conda environments.
utils::sessionInfo()## R version 4.3.1 (2023-06-16)
## Platform: aarch64-apple-darwin20 (64-bit)
## Running under: macOS Sonoma 14.3
##
## Matrix products: default
## BLAS: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRlapack.dylib; LAPACK version 3.11.0
##
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
##
## time zone: Europe/London
## tzcode source: internal
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## loaded via a namespace (and not attached):
## [1] gtable_0.3.4 jsonlite_1.8.8 renv_1.0.3
## [4] dplyr_1.1.4 compiler_4.3.1 BiocManager_1.30.22
## [7] tidyselect_1.2.0 rvcheck_0.2.1 scales_1.3.0
## [10] yaml_2.3.8 fastmap_1.1.1 here_1.0.1
## [13] ggplot2_3.4.4 R6_2.5.1 generics_0.1.3
## [16] knitr_1.45 yulab.utils_0.1.3 tibble_3.2.1
## [19] desc_1.4.3 dlstats_0.1.7 rprojroot_2.0.4
## [22] munsell_0.5.0 pillar_1.9.0 RColorBrewer_1.1-3
## [25] rlang_1.1.3 utf8_1.2.4 cachem_1.0.8
## [28] badger_0.2.3 xfun_0.41 fs_1.6.3
## [31] memoise_2.0.1.9000 cli_3.6.2 magrittr_2.0.3
## [34] rworkflows_1.0.1 digest_0.6.34 grid_4.3.1
## [37] rstudioapi_0.15.0 lifecycle_1.0.4 vctrs_0.6.5
## [40] data.table_1.14.10 evaluate_0.23 glue_1.7.0
## [43] fansi_1.0.6 colorspace_2.1-0 rmarkdown_2.25
## [46] tools_4.3.1 pkgconfig_2.0.3 htmltools_0.5.7