# Get Started

####

####
Authors: Brian Schilder, Alan Murphy, Hiranyamaya (Hiru) Dash, Nathan Skene

####

####
Vignette updated: Jan-08-2026

    library(rworkflows)

# GitHub Secrets

Before pushing changes to your new R package, you may want to set up one or more GitHub Secrets:

- `GITHUB_TOKEN` [Optional]: Can grant access to private repos on GitHub Actions. You can generate your very own Personal Authentication Token using these instructions.
- `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.

# `use_workflow`

## dynamic action

User only have to run `use_workflow` once per R package to create a workflow file that calls the `rworkflows` action.

    workflow <- rworkflows::use_workflow(run_bioccheck = FALSE,
                                         run_rcmdcheck = TRUE,
                                         run_pkgdown = TRUE,
                                         run_docker = TRUE,
                                         docker_user = "bschilder",
                                         docker_org = "neurogenomicslab",
                                         force_new = TRUE,
                                         ## Use default save_dir in practice
                                         save_dir = tempdir())

    ## Saving yaml ==> /var/folders/x7/97p7bsjj3tg3y7vvq_mwjggc0000gn/T//RtmpJ65xx6/rworkflows.yml

## static workflow

Alternatively, you may use

    workflow_static <- rworkflows::use_workflow(name = "rworkflows_static",
                                         run_bioccheck = FALSE,
                                         run_rcmdcheck = TRUE,
                                         run_pkgdown = TRUE,
                                         run_docker = TRUE,
                                         docker_user = "bschilder",
                                         docker_org = "neurogenomicslab",
                                         force_new = TRUE,
                                         ## Use default save_dir in practice
                                         save_dir = tempdir())

    ## Saving yaml ==> /var/folders/x7/97p7bsjj3tg3y7vvq_mwjggc0000gn/T//RtmpJ65xx6/rworkflows_static.yml

# `use_badges`

This function creates a banner containing badges, a hex sticker (if one is available), and author names.

    badges <- rworkflows::use_badges()

    ## Finding hex sticker(s) for 1 package(s).

    ## Adding license.

    ## Adding version.

    ## package is up-to-date devel version

    ## Adding code size

    ## Adding commit.

    ## Adding actions.

    ## Adding codecov.

    ## Adding authors.

    ## When refs is provided, paths must have the same length (or be set to NULL). Setting paths=NULL.

#### Authors: Brian Schilder, Alan Murphy, Hiranyamaya (Hiru) Dash, Nathan Skene

# `use_dockerfile`

Create a Dockerfile that installs your R package and all its Imports/Suggests. It is normally not necessary for users to run this function themselves unless they would like to use it to create a template Dockerfile and then customise it further (rather than creating one on the fly).

    ## Use default save_dir in practice
    dockerfile <- rworkflows::use_dockerfile(save_dir = tempdir())

    ## Creating new Docker file ==> /var/folders/x7/97p7bsjj3tg3y7vvq_mwjggc0000gn/T//RtmpJ65xx6/Dockerfile

# Templates

You can generate templates for each of the following R package elements. These templates are designed to dynamically autofill as as much information as possible (package name, date, authors) to minimise manual editing steps and ensure documentation is as up-to-date as possible.

## README

README rmarkdown file. Allows you to run code inside to generate a README markdown file.

    ## Use default save_dir in practice
    readme <- rworkflows::use_readme(save_dir = tempdir())

    ## Creating new README file ==> /var/folders/x7/97p7bsjj3tg3y7vvq_mwjggc0000gn/T//RtmpJ65xx6/README.Rmd

## Vignette: Get started

Generate a vignette on how to get started with your R package. Requires additional editing to fill in examples.

    ## Use default save_dir in practice
    vignette1 <- rworkflows::use_vignette_getstarted(package = "mypackage",
                                                     save_dir = tempdir())

    ## Creating new vignette file ==> /var/folders/x7/97p7bsjj3tg3y7vvq_mwjggc0000gn/T//RtmpJ65xx6/vignettes/mypackage.Rmd

## Vignette: docker

Generate a vignette on how to install your R package via with your R package, RStudio, and all dependencies already installed. This vignette does not require any manual editing after creation (unless you want to change things like port number, for example).

Note, this is only relevant when you have a container for your R package stored in a public Docker registry (e.g. GitHub Container Registry, DockerHub). You can automatically generate one by using the `rworkflows` action with `run_docker=TRUE`:

    rworkflows::use_workflow(run_docker = TRUE,
                             docker_org = "neurogenomics")

If you’re using the GitHub Container Registry, `docker_org` can simply be your GH organization name or user name.

    ## Use default save_dir in practice
    vignette2 <- rworkflows::use_vignette_docker(docker_org = "neurogenomics",
                                                 save_dir = tempdir())

    ## Creating new vignette file ==> /var/folders/x7/97p7bsjj3tg3y7vvq_mwjggc0000gn/T//RtmpJ65xx6/vignettes/docker.Rmd

# Adding Python

If your R package depends on python (e.g. via `reticulate`), the `rworkflows` action can also automatically install python for you.

## Using Python

You can instruct GitHub Actions to install a version of python, with whatever level of versioning specificiy you want (e.g. “3.10.11”, “3.10”, or even just “3”).

If you supply one `python_version`, it will be applied to all runners. You also assign a different `python_version` to each `os`, as we do here:

    runners <- rworkflows::construct_runners(
      python_version = list("ubuntu-latest"="3.10.11",
                            "macOS-latest"="3.9",
                            "windows-latest"="3.9.1"))
    workflow <- rworkflows::use_workflow(runners = runners,
                                         preview = TRUE,
                                         force_new = TRUE,
                                         ## Use default save_dir in practice
                                         save_dir = tempdir())

    ## name: rworkflows
    ## 'on':
    ##   push:
    ##     branches:
    ##     - master
    ##     - main
    ##     - devel
    ##     - RELEASE_**
    ##   pull_request:
    ##     branches:
    ##     - master
    ##     - main
    ##     - devel
    ##     - RELEASE_**
    ## jobs:
    ##   rworkflows:
    ##     permissions: write-all
    ##     runs-on: ${{ matrix.config.os }}
    ##     name: ${{ matrix.config.os }} (${{ matrix.config.r }})
    ##     container: ${{ matrix.config.cont }}
    ##     strategy:
    ##       fail-fast: no
    ##       matrix:
    ##         config:
    ##         - os: ubuntu-latest
    ##           bioc: devel
    ##           r: auto
    ##           cont: ghcr.io/bioconductor/bioconductor_docker:devel
    ##           rspm: ~
    ##           python-version: 3.10.11
    ##         - os: macOS-latest
    ##           bioc: release
    ##           r: auto
    ##           cont: ~
    ##           rspm: ~
    ##           python-version: '3.9'
    ##         - os: windows-latest
    ##           bioc: release
    ##           r: auto
    ##           cont: ~
    ##           rspm: ~
    ##           python-version: 3.9.1
    ##     steps:
    ##     - uses: neurogenomics/rworkflows@master
    ##       with:
    ##         run_bioccheck: no
    ##         run_rcmdcheck: yes
    ##         as_cran: yes
    ##         run_vignettes: yes
    ##         has_testthat: yes
    ##         run_covr: yes
    ##         run_pkgdown: yes
    ##         has_runit: no
    ##         has_latex: no
    ##         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    ##         run_docker: no
    ##         DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }}
    ##         CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
    ##         runner_os: ${{ runner.os }}
    ##         cache_version: cache-v1
    ##         ncpus: 2.0
    ##         docker_registry: ghcr.io

    ## Saving yaml ==> /var/folders/x7/97p7bsjj3tg3y7vvq_mwjggc0000gn/T//RtmpJ65xx6/rworkflows.yml

## Using conda

Optionally, you can tell it to create and activate a conda environment to use. `rworkflows::construct_conda_yml` is a helper function to create conda yaml files for you.

Here we construct our yaml file that specifies what we want in our conda env. Make sure you write the yaml to your project directory, so that it gets pushed to GitHub (and thus can be found after checking out your repo on GitHub Actions).

See here for some examples of

    environment_file <- construct_conda_yml(name = "myenv",
                                            channels = c("conda-forge",
                                                         "bioconda"),
                                            dependencies = c("python>=3.7",
                                                             "scanpy",
                                                             "anndata"),
                                            pip = c("scarches",
                                                    "magic-impute"),
                                            preview = TRUE)

    ## name: myenv
    ## channels:
    ## - conda-forge
    ## - bioconda
    ## dependencies:
    ## - python>=3.7
    ## - scanpy
    ## - anndata
    ## - pip
    ## - pip:
    ##   - scarches
    ##   - magic-impute

    ## Saving yaml ==> /private/var/folders/x7/97p7bsjj3tg3y7vvq_mwjggc0000gn/T/RtmpjjEhtk/Rbuild503f3ce55884/rworkflows/myenv_conda.yml

You could also simply provide a URL to a publicly accessible conda yaml file stored elsewhere.

    environment_file <- "https://github.com/RajLabMSSM/echoconda/raw/main/inst/conda/scanpy.yml"

Now we can supply the conda `environment_file` path, and Miniconda will automatically be installed to build the conda env on all of your GitHub Actions runners.

    workflow <- rworkflows::use_workflow(environment_file = environment_file,
                                         preview = TRUE,
                                         force_new = TRUE,
                                         ## Use default save_dir in practice
                                         save_dir = tempdir())

    ## environment_file supplied. Enabling miniforge.

    ## python-version not set for runner os='ubuntu-latest'. Using default.

    ## python-version not set for runner os='macOS-latest'. Using default.

    ## python-version not set for runner os='windows-latest'. Using default.

    ## name: rworkflows
    ## 'on':
    ##   push:
    ##     branches:
    ##     - master
    ##     - main
    ##     - devel
    ##     - RELEASE_**
    ##   pull_request:
    ##     branches:
    ##     - master
    ##     - main
    ##     - devel
    ##     - RELEASE_**
    ## jobs:
    ##   rworkflows:
    ##     permissions: write-all
    ##     runs-on: ${{ matrix.config.os }}
    ##     name: ${{ matrix.config.os }} (${{ matrix.config.r }})
    ##     container: ${{ matrix.config.cont }}
    ##     strategy:
    ##       fail-fast: no
    ##       matrix:
    ##         config:
    ##         - os: ubuntu-latest
    ##           bioc: devel
    ##           r: auto
    ##           cont: ghcr.io/bioconductor/bioconductor_docker:devel
    ##           rspm: ~
    ##         - os: macOS-latest
    ##           bioc: release
    ##           r: auto
    ##           cont: ~
    ##           rspm: ~
    ##         - os: windows-latest
    ##           bioc: release
    ##           r: auto
    ##           cont: ~
    ##           rspm: ~
    ##     steps:
    ##     - uses: neurogenomics/rworkflows@master
    ##       with:
    ##         run_bioccheck: no
    ##         run_rcmdcheck: yes
    ##         as_cran: yes
    ##         run_vignettes: yes
    ##         has_testthat: yes
    ##         run_covr: yes
    ##         run_pkgdown: yes
    ##         has_runit: no
    ##         has_latex: no
    ##         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    ##         run_docker: no
    ##         DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }}
    ##         CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
    ##         runner_os: ${{ runner.os }}
    ##         cache_version: cache-v1
    ##         ncpus: 2.0
    ##         docker_registry: ghcr.io
    ##         miniforge_variant: ''
    ##         environment_file: /private/var/folders/x7/97p7bsjj3tg3y7vvq_mwjggc0000gn/T/RtmpjjEhtk/Rbuild503f3ce55884/rworkflows/myenv_conda.yml

    ## Saving yaml ==> /var/folders/x7/97p7bsjj3tg3y7vvq_mwjggc0000gn/T//RtmpJ65xx6/rworkflows.yml

    ## Cleanup files
    try({file.remove(environment_file)})

    ## [1] TRUE

# Session Info

    utils::sessionInfo()

    ## R version 4.5.1 (2025-06-13)
    ## Platform: aarch64-apple-darwin20
    ## Running under: macOS Tahoe 26.1
    ##
    ## Matrix products: default
    ## BLAS:   /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRblas.0.dylib
    ## LAPACK: /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    ##
    ## locale:
    ## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    ##
    ## time zone: America/Mexico_City
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] data.table_1.18.0 rworkflows_1.0.8
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] gtable_0.3.6        jsonlite_2.0.0      renv_1.1.5
    ##  [4] dplyr_1.1.4         compiler_4.5.1      BiocManager_1.30.27
    ##  [7] tidyselect_1.2.1    dichromat_2.0-0.1   jquerylib_0.1.4
    ## [10] rvcheck_0.2.1       scales_1.4.0        yaml_2.3.12
    ## [13] fastmap_1.2.0       here_1.0.2          ggplot2_4.0.1
    ## [16] R6_2.6.1            generics_0.1.4      knitr_1.51
    ## [19] yulab.utils_0.2.3   tibble_3.3.0        desc_1.4.3
    ## [22] dlstats_0.1.7       rprojroot_2.1.1     bslib_0.9.0
    ## [25] pillar_1.11.1       RColorBrewer_1.1-3  rlang_1.1.6
    ## [28] cachem_1.1.0        badger_0.2.5        xfun_0.55
    ## [31] fs_1.6.6            sass_0.4.10         S7_0.2.1
    ## [34] otel_0.2.0          cli_3.6.5           magrittr_2.0.4
    ## [37] digest_0.6.39       grid_4.5.1          rstudioapi_0.17.1
    ## [40] rappdirs_0.3.3      lifecycle_1.0.4     vctrs_0.6.5
    ## [43] evaluate_1.0.5      glue_1.8.0          farver_2.1.2
    ## [46] rmarkdown_2.30      tools_4.5.1         pkgconfig_2.0.3
    ## [49] htmltools_0.5.9