README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
print_yaml <- function(filename) {
  cat("```yaml", readLines(filename), "```", sep = "\n")
}
```

# Example workflows

Package workflows:

- [`check-release`](#quickstart-ci-workflow) - A simple CI workflow to check with the release version of R.
- [`check-standard`](#standard-ci-workflow) - A standard CI workflow to check with the release version of R on the three major OSs.
- [`check-full`](#tidyverse-ci-workflow) - A more complex CI workflow
- [`test-coverage`](#test-coverage-workflow) - Run `covr::codecov()` on an R package.
- [`lint`](#lint-workflow) - Run `lintr::lint_package()` on an R package.
- [`pr-commands`](#commands-workflow) - Adds `/document` and `/style` commands for pull requests.
- [`pkgdown`](#build-pkgdown-site) - Build a [pkgdown] site for an R package and deploy it to [GitHub Pages] or [Cloudflare Pages].
- [`document`](#document-package) - Run `roxygen2::roxygenise()` on an R package.
- [`style`](#style-package) - Run `styler::style_pkg()` on an R package.

RMarkdown workflows:

- [`render-rmarkdown`](#render-rmarkdown) - Render one or more Rmarkdown files when they change and commit the result.
- [`bookdown`](#build-bookdown-site) - Build a [bookdown] site and deploy it to [GitHub Pages] or [Cloudflare Pages].
- [`bookdown-gh-pages`](#build-bookdown-site-alternative-workflow) - Alternative workflow to build a [bookdown] site and deploy it to [GitHub Pages].
- [`blogdown`](#build-blogdown-site) - Build a [blogdown] site and deploy it to [GitHub Pages] or [Cloudflare Pages].
- [`blogdown-gh-pages`](#build-blogdown-site-alternative-workflow) - Alternative workflow to build a [blogdown] site and deploy it to [GitHub Pages].

Other workflows:

- [Bioconductor](#bioconductor-friendly-workflow) - A CI workflow for packages to be released on Bioconductor.
- [`lint-project`](#lint-project-workflow) - Run `lintr::lint_dir()` on an R project.
- [`shiny-deploy`](#shiny-app-deployment) - Deploy a Shiny app to shinyapps.io or RStudio Connect.

Options and advice:

- [Forcing binaries](#forcing-binaries) - An environment variable to always use binary packages.

## Quickstart CI workflow

`usethis::use_github_action("check-release")`

This workflow installs latest release R version on linux
and runs R CMD check via the [rcmdcheck](https://github.com/r-lib/rcmdcheck)
package. If this is the first time you have used CI for a project this is
probably what you want to use.

### When should you use it?

1. You have a simple R package
2. There is no OS-specific code
3. You want a quick start with R CI

```{r echo = FALSE, results = "asis"}
print_yaml("check-release.yaml")
```

## Standard CI workflow

`usethis::use_github_action("check-standard")`

This workflow runs R CMD check via the
[rcmdcheck](https://github.com/r-lib/rcmdcheck) package on the three major OSs
(linux, macOS and Windows) with the current, development, and previous versions
of R. If you plan to someday submit your package to CRAN or Bioconductor this is
likely the workflow you want to use.

### When should you use it?

1. You plan to submit your package to CRAN or Bioconductor
2. Your package has OS-specific code

```{r echo = FALSE, results = "asis"}
print_yaml("check-standard.yaml")
```

## Tidyverse CI workflow

`usethis::use_github_action("check-full")`

This workflow installs the last 5 minor R versions
and runs R CMD check via the [rcmdcheck](https://github.com/r-lib/rcmdcheck)
package on the three major OSs (linux, macOS and Windows). This workflow is
what the tidyverse teams uses on their repositories, but is overkill
for less widely used packages, which are better off using the simpler
quickstart CI workflow.

### When should you use it?

1. You are a tidyverse developer
2. You have a complex R package
3. With OS-specific code
4. And you want to ensure compatibility with many older R versions

```{r echo = FALSE, results = "asis"}
print_yaml("check-full.yaml")
```

## Test coverage workflow

`usethis::use_github_action("test-coverage")`

This example uses the [covr](https://covr.r-lib.org) package to query the test
coverage of your package and upload the result to
[codecov.io](https://codecov.io)

In theory reporting to codecov.io works automatically, but unfortunately
in practice it often fails, unless a `CODECOV_TOKEN` secret is set
in the repository, containing a Codecov repository upload token.

If you use the `codecov/codecov-action` action to upload your test results
to GitHub, like the example here, then you can also use a global
organization token in an organization secret called `CODECOV_TOKEN`.
This way you can avoid having to add a secret to each repository of your
organization. You can find this token at
`https://app.codecov.io/account/gh/<org>/org-upload-token` where `<org>` is
your GitHub organization. E.g. for `r-lib` it is at
https://app.codecov.io/account/gh/r-lib/org-upload-token.
To see it, you'll need log in to Codecov, and you need to be a Codecov
admin for the organization.

```{r echo = FALSE, results = "asis"}
print_yaml("test-coverage.yaml")
```

## Lint workflow

`usethis::use_github_action("lint")`

This example uses the [lintr](https://github.com/r-lib/lintr) package to lint your package and return the results as build annotations.

```{r echo = FALSE, results = "asis"}
print_yaml("lint.yaml")
```

## Commands workflow

`usethis::use_github_action("pr-commands")`

This workflow enables the use of 2 R specific commands in pull request issue
comments. `/document` will use [roxygen2](https://roxygen2.r-lib.org/) to
rebuild the documentation for the package and commit the result to the pull
request. `/style` will use [styler](https://styler.r-lib.org/) to restyle your
package.

### When should you use it?

1. You get frequent pull requests, often with documentation only fixes.
2. You regularly style your code with styler, and require all additions be
   styled as well.

```{r echo = FALSE, results = "asis"}
print_yaml("pr-commands.yaml")
```

## Render Rmarkdown

`usethis::use_github_action("render-rmarkdown")`

This example automatically re-builds any Rmarkdown file in the repository whenever it changes and commits the results to the same branch.

```{r echo = FALSE, results = "asis"}
print_yaml("render-rmarkdown.yaml")
```

## Build pkgdown site

`usethis::use_github_action("pkgdown")`

This example builds a [pkgdown] site for a repository and pushes the built package
to [GitHub Pages] or [Cloudflare Pages].
The inclusion of [`workflow_dispatch`](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#workflow_dispatch) means the workflow can be [run manually, from the browser](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow), or [triggered via the GitHub REST API](https://docs.github.com/en/rest/reference/actions/#create-a-workflow-dispatch-event).

You'll need to update your setting on GitHub to deploy the `gh-pages`
(unless configured otherwise) branch of your repository to GitHub Pages.

Similarly, connect your Cloudflare Pages app to the `gh-pages` branch of
your repository on your Cloudflare dashboard. You'll need to set
`exit 0` as the build command for pkgdown sites. See the Cloudflare Pages
documentation for details.

```{r echo = FALSE, results = "asis"}
print_yaml("pkgdown.yaml")
```

## Document package

`usethis::use_github_action("document")`

This example documents an R package whenever a file in the `R/` directory changes, then commits and pushes the changes
to the same branch.

```{r echo = FALSE, results = "asis"}
print_yaml("document.yaml")
```

## Style package

`usethis::use_github_action("style")`

This example styles the R code in a package, then commits and pushes the changes
to the same branch.

```{r echo = FALSE, results = "asis"}
print_yaml("style.yaml")
```

## Build bookdown site

`usethis::use_github_action("bookdown")`

This example builds a [bookdown] site for a repository and then deploys the site via [GitHub Pages] or Cloudflare Pages.
It uses [renv] to ensure the package versions remain consistent across builds.
You will need to run `renv::snapshot()` locally and commit the `renv.lock` file before using this workflow, and after every time you add a new package to `DESCRIPTION`. See [Using renv with Continous Integration](https://rstudio.github.io/renv/articles/ci.html) for additional information.

You'll need to update your setting on GitHub to deploy the `_book`
folder of the `gh-pages` branch (unless configured otherwise)
of your repository to GitHub Pages.

Similarly, connect your Cloudflare Pages app to the `gh-pages` branch of
your repository on your Cloudflare dashboard. You'll need to set
`exit 0` as the build command for bookdown sites. See the Cloudflare
Pages documentation for details.

```{r echo = FALSE, results = "asis"}
print_yaml("bookdown.yaml")
```

## Build bookdown site, alternative workflow

`usethis::use_github_action("bookdown-gh-pages")`

This is an alternative workflow that builds and publishes a bookdown book,
without creating a separate branch in the repository for the built book.

```{r echo = FALSE, results = "asis"}
print_yaml("bookdown-gh-pages.yaml")
```

## Build blogdown site

`usethis::use_github_action("blogdown")`

This example builds a [blogdown] site for a repository and then deploys the book via [GitHub Pages] or Cloudflare Pages.
It uses [renv] to ensure the package versions remain consistent across builds.
You will need to run `renv::snapshot()` locally and commit the `renv.lock` file before using this workflow, see [Using renv with Continous Integration](https://rstudio.github.io/renv/articles/ci.html) for additional information.

You'll need to update your setting on GitHub to deploy the `public`
folder of the `gh-pages` branch (unless configured otherwise)
of your repository to GitHub Pages.

Similarly, connect your Cloudflare Pages app to the `gh-pages` branch of
your repository on your Cloudflare dashboard. You'll need to set
`exit 0` as the build command for blogdown sites. See the Cloudflare
Pages documentation for details.

```{r echo = FALSE, results = "asis"}
print_yaml("blogdown.yaml")
```
## Build blogdown site, alternative workflow

`usethis::use_github_action("blogdown-gh-pages")`

This is an alternative workflow that builds and publishes a blogdown site,
without creating a separate branch in the repository for the built site.

```{r echo = FALSE, results = "asis"}
print_yaml("blogdown-gh-pages.yaml")
```

## Shiny App Deployment

`usethis::use_github_action("shiny-deploy")`

This example will deploy your Shiny application to either [shinyapps.io](https://www.shinyapps.io/) or [RStudio Connect](https://www.rstudio.com/products/connect/) using the `rsconnect` package. The `rsconnect` package requires authorization to deploy an app using your account. This action does this by using your user name (`RSCONNECT_USER`), token (`RSCONNECT_TOKEN`), and secret (`RSCONNECT_SECRET`), which are securely accessed as GitHub Secrets. **Your token and secret are private and should be kept confidential**.

This action assumes you have an `renv` lockfile in your repository that describes the `R` packages and versions required for your Shiny application.

- See here for information on how to obtain the token and secret for configuring `rsconnect`: https://shiny.rstudio.com/articles/shinyapps.html

- See here for information on how to store private tokens in a repository as GitHub Secrets: https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository

```{r echo = FALSE, results = "asis"}
print_yaml("shiny-deploy.yaml")
```

## Bioconductor-friendly workflow

[Bioconductor](http://bioconductor.org/) is a repository for tools for
the analysis and comprehension of high-throughput genomic data that
hosts close to 2,000 R packages. It follows a six month release cycle
while R has a yearly release cycle. `biocthis` contains a
user-contributed workflow that is Bioconductor-friendly described in
detail at[the `biocthis` introductory vignette](https://lcolladotor.github.io/biocthis/articles/biocthis.html#use-bioc-github-action-).
You can add this workflow using the following R code:

```{r biocthis_gha, eval = FALSE}
## If needed
remotes::install_github("lcolladotor/biocthis")

## Create a GitHub Actions (GHA) workflow that is Bioconductor-friendly
biocthis::use_bioc_github_action()

## You can also use this GHA workflow without installing biocthis
usethis::use_github_action(
    "check-bioc",
    "https://bit.ly/biocthis_gha",
    "check-bioc.yml"
)
```


## Lint project workflow

`usethis::use_github_action("lint-project")`

This example uses the [lintr](https://github.com/r-lib/lintr) package to lint your project and return the results as annotations.

```{r echo = FALSE, results = "asis"}
print_yaml("lint-project.yaml")
```


## Forcing binaries

Code repositories such as [CRAN](http://cran.r-project.org) or [RStudio](http://rstudio.com)'s RSPM provide R packages in binary (= pre-compiled) form for some platforms, but these binaries can sometimes be missing or lag behind the package sources published on the repository.
The [setup-r](https://github.com/r-lib/actions/tree/v2/setup-r) action, and all example workflows utilizing it follow the `install.packages.compile.from.source` `options()` default and will install from source when a binary is out of date.
Installing from source can be slow and require additional system dependencies, but ensures that your workflow runs against the current versions of dependencies.

To always use binaries, even if they are out of date, set the environment variable `R_COMPILE_AND_INSTALL_PACKAGES=never`.
You can set an environment variable by passing it as a name-value pair to the `jobs.<job_id>.env` keyword, as in this partial example:

```{yaml}
jobs:
  R-CMD-check:
   # missing yaml here
    env:
      R_COMPILE_AND_INSTALL_PACKAGES: never
   # missing yaml here
```

`R_COMPILE_AND_INSTALL_PACKAGES: never` does what it says on the tin: it will never install from source.
If there is *no* binary for the package, or none meeting the minimum version required in your `DESCRIPTION`, the installation of R package dependencies will be incomplete.
This can lead to confusing errors, because while dependency installation will *not* fail in this situation, later steps in your workflow may fail because of the missing package(s).

You can learn more about packages in source and binary form [here](https://r-pkgs.org/package-structure-state.html#binary-package) and [here](https://www.jumpingrivers.com/blog/faster-r-package-installation-rstudio/).

[GitHub Pages]: https://pages.github.com/
[Cloudflare Pages]: https://pages.cloudflare.com/
[renv]: https://rstudio.github.io/renv/
[pkgdown]: https://pkgdown.r-lib.org/
[bookdown]: https://bookdown.org
[blogdown]: https://bookdown.org/yihui/blogdown/