https://github.com/neurogenomics/rworkflows

Continuous integration for R packages. 🔀 Automates testing ✅, documentation website building 📦, & containerised deployment 🐳.
https://github.com/neurogenomics/rworkflows

bioconductor containers continuous-integration cran-r docker dockerhub github-actions r reproducibility workflows

Last synced: 10 days ago
JSON representation

Continuous integration for R packages. 🔀 Automates testing ✅, documentation website building 📦, & containerised deployment 🐳.

Host: GitHub
URL: https://github.com/neurogenomics/rworkflows
Owner: neurogenomics
Created: 2021-10-28T15:44:27.000Z (over 3 years ago)
Default Branch: master
Last Pushed: 2025-03-17T15:48:55.000Z (29 days ago)
Last Synced: 2025-03-29T07:06:32.521Z (17 days ago)
Topics: bioconductor, containers, continuous-integration, cran-r, docker, dockerhub, github-actions, r, reproducibility, workflows
Language: HTML
Homepage: https://neurogenomics.github.io/rworkflows/
Size: 12.4 MB
Stars: 79
Watchers: 2
Forks: 7
Open Issues: 33
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md

Awesome Lists containing this project

jimsghstars - neurogenomics/rworkflows - Continuous integration for R packages. 🔀 Automates testing ✅, documentation website building 📦, & containerised deployment 🐳. (HTML)

README

        ---

title: ""  

author: "`r rworkflows::use_badges(add_actions=c('rworkflows','rworkflows_static','rworkflows_dev'), add_cran_release = TRUE, add_cran_checks = FALSE, add_cran_download_month=TRUE, add_cran_download_total=TRUE, add_codecov_graphs='icicle', hex_height=350, add_doi='https://doi.org/10.5281/zenodo.10048573')`" 

date: "
README updated: `r format( Sys.Date(), '%b-%d-%Y')`

"

output:

  github_document

---

[![CRAN checks](https://badges.cranchecks.info/worst/rworkflows.svg)](https://cran.r-project.org/web/checks/check_results_rworkflows.html)

```{r setup, include=FALSE}

pkg <- read.dcf("DESCRIPTION", fields = "Package")[1]

```

## Citation 

If you use ``r pkg``, please cite: 

> `r utils::citation(pkg)$textVersion`

## 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**](https://github.com/neurogenomics/templateR): a `CRAN`/`Bioc`-compatible R package template that automatically generates essential documentation using package metadata.  

2. [**`rworkflows` R package**](https://github.com/neurogenomics/rworkflows/blob/master/DESCRIPTION): a lightweight `CRAN` package to automatically 

set up short, customisable workflows that trigger the `rworkflows` action.  

3. [**`rworkflows` action**](https://github.com/neurogenomics/rworkflows/blob/master/action.yml): an open-source action available on the [GitHub Actions  Marketplace](https://github.com/marketplace/actions/rworkflows). 

### `rworkflows` action steps 

[**GitHub Actions**](https://docs.github.com/en/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)**](https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration),

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**](https://cran.r-project.org/)

and/or [**Bioconductor**](https://bioconductor.org/) checks).  

7. 📋 Runs [unit tests](https://testthat.r-lib.org/).  

8. 📋 Runs [code coverage tests](https://covr.r-lib.org/) and uploads the results 

to [**Codecov**](https://about.codecov.io/).  

9. 🚀 (Re)builds and launches a documentation website for your R package.  

10. 🐳 Pushes a [**Docker**](https://www.docker.com/) container (with [**Rstudio**](https://posit.co/) and all dependencies pre-installed) to 

your choice of container registry (e.g. [**GitHub Container Registry**](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry),  [**DockerHub**](https://hub.docker.com/)). 

11. 🔭 Generates [workflow telemetry](https://github.com/catchpoint/workflow-telemetry-action) 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`](https://github.com/lcolladotor/biocthis), [`usethis`](https://github.com/r-lib/usethis), [`actions/`](https://github.com/actions), [`r-lib/actions`](https://github.com/r-lib/actions), [`bioc-actions`](https://github.com/grimbough/bioc-actions), [`JamesIves/github-pages-deploy-action`](https://github.com/JamesIves/github-pages-deploy-action), [`docker/build-push-action`](https://github.com/docker/build-push-action), [`bioconductor_docker`](https://github.com/Bioconductor/bioconductor_docker). For more details on how these projects relate to `rworkflows`, please see [below](#acknowledgments).

 

## Quickstart

Install and create the workflow in your R package's project folder.

```R

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

```bash

## 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](https://neurogenomics.github.io/rworkflows/articles/)

#### [Get started](https://neurogenomics.github.io/rworkflows/articles/rworkflows.html) 

Introductory vignette for using `rworkflows`.

#### [Docker/Singularity](https://neurogenomics.github.io/rworkflows/articles/docker)  

Copy-and-paste instructions for creating a **Docker** or **Singularity** container

with the `rworkflows` R package pre-installed.  

#### [Dependency graph](https://neurogenomics.github.io/rworkflows/articles/depgraph). 

Interactive graph showing all the GitHub repos that currently use 

the `rworkflows` action.

### [Videos](https://www.youtube.com/@NeurogenomicsLab)

#### [rworkflows: taming the Wild West of R packages](https://youtu.be/nLIG2prEmCg) 

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

#### [Getting into the flow with rworkflows: an introductory tutorial](https://youtu.be/vcpMsil3EAU)

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](https://docs.github.com/en/actions/security-guides/encrypted-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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for details.   

* `DOCKER_TOKEN` [Optional]: Allows GitHub Actions to push to a

    [DockerHub](https://hub.docker.com) account. 

## Acknowledgments

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

### [`biocthis`](https://github.com/lcolladotor/biocthis)

This workflow is largely inspired by the workflow generated by the 

[`use_bioc_github_action()`](https://lcolladotor.github.io/biocthis/articles/biocthis.html) function within the 

[`biothis`]( https://www.bioconductor.org/packages/release/bioc/html/biocthis.html) 

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`](https://github.com/r-lib/usethis)

`biocthis` was in turn inspired by `usethis`.

### [`actions/`](https://github.com/actions)

A general set of **GitHub Actions** maintained by the core GitHub team.

### [`r-lib/actions`](https://github.com/r-lib/actions)

A set of **GitHub Actions** for R development maintained by the Rstudio/Posit team.

### [`bioc-actions`](https://github.com/grimbough/bioc-actions)

[Bioconductor](https://www.bioconductor.org/)-oriented **GitHub Actions** created by @grimbough.

### [`JamesIves/github-pages-deploy-action`](https://github.com/JamesIves/github-pages-deploy-action)

Builds and deploys the **GitHub Pages** documentation website

in the `rworkflows` GHA workflows.

### [`docker/build-push-action`](https://github.com/docker/build-push-action)

A set of **GitHub Actions** for building/pushing **Docker** containers.

### [`bioconductor_docker`](https://github.com/Bioconductor/bioconductor_docker)

Uses the official 

[`bioconductor/bioconductor_docker`](https://github.com/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](https://github.com/Bioconductor/bioconductor_docker/issues/37), and the [Bioconductor release schedule](https://www.bioconductor.org/about/release-announcements/). 

### [`scFlow`](https://github.com/combiz/scFlow)

This Dockerfile was partly adapted from the [scFlow Dockerfile](https://github.com/combiz/scFlow/blob/master/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. 

### [`act`](https://github.com/nektos/act)

A very useful command line tool for testing **GitHub Actions** locally. 

### [`actions/runner-images`](https://github.com/actions/runner-images)

Runner images for each OS provided by GitHub.

### [`actions/setup-miniconda`](https://github.com/marketplace/actions/setup-miniconda)

GitHub Action to setup Miniconda and conda environments.

# Session Info  

```{r}

utils::sessionInfo()

```

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/neurogenomics/rworkflows

Awesome Lists containing this project

README

README updated: `r format( Sys.Date(), '%b-%d-%Y')`