Permalink
Cannot retrieve contributors at this time
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
321 lines (221 sloc)
13.7 KB
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| --- | |
| 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]. | |
| 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 [netlify]. | |
| - [`blogdown`](#build-blogdown-site) - Build a [blogdown] site and deploy it to [netlify]. | |
| Other workflows: | |
| - [`docker`](#docker-based-workflow) - For custom workflows based on docker containers. | |
| - [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. | |
| - [Managing secrets](#managing-secrets) - How to generate auth tokens and make them available to actions. | |
| ## Quickstart CI workflow | |
| `usethis::use_github_action("check-release")` | |
| This workflow installs latest release R version on macOS | |
| 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) | |
| ```{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/jimhester/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 master 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]. | |
| 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). | |
| ```{r echo = FALSE, results = "asis"} | |
| print_yaml("pkgdown.yaml") | |
| ``` | |
| ## Build bookdown site | |
| `usethis::use_github_action("bookdown")` | |
| This example builds a [bookdown] site for a repository and then deploys the site via [netlify]. | |
| 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. | |
| **Note** you need to add a `NETLIFY_AUTH_TOKEN` and a `NETLIFY_SITE_ID` secret to your repository for the netlify deploy (see [Managing secrets](#managing-secrets) section for details). | |
| ```{r echo = FALSE, results = "asis"} | |
| print_yaml("bookdown.yaml") | |
| ``` | |
| ## Build blogdown site | |
| `usethis::use_github_action("blogdown")` | |
| This example builds a [blogdown] site for a repository and then deploys the book via [netlify]. | |
| 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. | |
| **Note** you need to add a `NETLIFY_AUTH_TOKEN` a `NETLIFY_SITE_ID` secret to your repository for the netlify deploy (see [Managing secrets](#managing-secrets) section for details). | |
| ```{r echo = FALSE, results = "asis"} | |
| print_yaml("blogdown.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") | |
| ``` | |
| ## Docker based workflow | |
| `usethis::use_github_action("docker")` | |
| If you develop locally with docker or are used to using other docker based CI | |
| services and already have a docker container with all of your R and system | |
| dependencies you can use that in GitHub Actions by adapting the following | |
| workflow. This example workflow assumes you build some model in `fit_model.R` | |
| and then have a report in `report.Rmd`. It then uploads the rendered html from | |
| the report as a build artifact. | |
| ```{r echo = FALSE, results = "asis"} | |
| print_yaml("docker.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/jimhester/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 our lag behind the package sources published on the repository. | |
| The [setup-r](https://github.com/r-lib/actions/tree/master/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/). | |
| ## Managing secrets | |
| In some cases, your action may need to access an external resource to deploy a result of your action. | |
| For example, the [bookdown]() and [blogdown]() actions require access to your Netlify account. | |
| This access is managed using a Personal Access Token, commonly called a PAT. | |
| Netlify has a [process for creating a PAT using their UI](https://docs.netlify.com/cli/get-started/#obtain-a-token-in-the-netlify-ui), which we follow here. | |
| 1. In a web browser, open [your Netlify **tokens** page](https://app.netlify.com/user/applications#personal-access-tokens). | |
| 2. In another tab in your web browser, open your GitHub repository's **secrets** page. The URL depends on your repository; it will look something like this: `https://github.com/{user}/{repo}/settings/secrets`. | |
| 3. At the **tokens** page: | |
| - Click "New access token". | |
| - Provide a description for your benefit, so you will know which token this is, perhaps something like `actions-{repo}`. | |
| - Click "Generate token". | |
| - Copy the token to your clipboard. | |
| 4. On your repository's **secrets** page: | |
| - Click "Add a new secret". | |
| - In the "Name" field, type `NETLIFY_AUTH_TOKEN` (or the name of the secret that the action expects). | |
| - In the "Value" field, paste the token from your clipboard. | |
| - Click "Add Secret". | |
| 5. At this point (certainly at some point), you may wish to close your **tokens** page to remove the visibility of your token. | |
| The `NETLIFY_SITE_ID` is not quite as personal as the PAT and is visible from your Netlify profile. This is the value of the **API ID** variable that is listed on your site dashboard under Settings > General > Site details > Site information. | |
| [GitHub Pages]: https://pages.github.com/ | |
| [renv]: https://rstudio.github.io/renv/ | |
| [pkgdown]: https://pkgdown.r-lib.org/ | |
| [bookdown]: https://bookdown.org | |
| [blogdown]: https://bookdown.org/yihui/blogdown/ | |
| [netlify]: https://www.netlify.com/ |