Rworkflows

<img src='https://github.com/neurogenomics/rworkflows/raw/master/inst/hex/hex.png' title='Hex sticker for rworkflows' height='350'><br> <br> <br> <br> <a href='https://app.codecov.io/gh/neurogenomics/rworkflows/tree/master' target='_blank'><img src='https://codecov.io/gh/neurogenomics/rworkflows/branch/master/graphs/icicle.svg' title='Codecov icicle graph' width='200' height='50' style='vertical-align: top;'></a>

<h4> Authors: <i>Brian Schilder, Alan Murphy, Hiranyamaya (Hiru) Dash, Nathan Skene</i> </h4> <h4> README updated: <i>Mar-23-2026</i> </h4>

Citation

If you use rworkflows, please cite:

<!-- Modify this by editing the file: inst/CITATION -->

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

Intro

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 steps

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/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):

1. 🐳 Builds a Docker container to run subsequent steps within.
2. 🐍 Builds and/or activates a custom conda environment.
3. 🛠️ Installs system dependencies
4. 🛠️ Installs LaTeX dependencies.
5. 🛠 Installs R dependencies.
6. ✅ Builds and checks your R package (with CRAN and/or Bioconductor checks).
7. 📋 Runs unit tests.
8. 📋 Runs code coverage tests and uploads the results to Codecov.
9. 🚀 (Re)builds and launches a documentation website for your R package.
10. 🐳 Pushes a Docker container (with Rstudio and all dependencies pre-installed) to your choice of container registry (e.g. GitHub Container Registry, DockerHub).
11. 🔭 Generates workflow telemetry report.
12. 🎖 Updates relevant badges added to your README with 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: 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 to rworkflows, please see below.

Quickstart

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]"

Documentation

Vignettes

Get started

Introductory vignette for using rworkflows.

Docker/Singularity

Copy-and-paste instructions for creating a Docker or Singularity container with the rworkflows R package pre-installed.

Dependency graph.

Interactive graph showing all the GitHub repos that currently use the rworkflows action.

Videos

rworkflows: taming the Wild West of R packages

Talk on the background, motivation, and utility of rworkflows.

Getting into the flow with rworkflows: an introductory tutorial

Step-by-step tutorial showing how to use rworkflows in an R package.

GitHub Secrets

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.
• CODECOV_TOKEN [Optional]: Codecov repository token to upload coverage reports. Providing this token helps prevent report upload failures by bypassing Codecov’s GitHub API rate limits. See the Codecov documentation for details.

Acknowledgments

rworkflows builds upon the work of many others, especially the following:

biocthis

This workflow is largely inspired by the workflow generated by the use_bioc_github_action() function within the biothis package, developed by @lcolladotor.

Key changes in rworkflows

• 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.

usethis

biocthis was in