Reusable GHA workflows

🚩🚩🚩 This repo is intended for internal use only. Sweeping changes will be made without notice. 🚩🚩🚩

A reusable workflow is a workflow that is defined in a single location but can be executed from another location as if it was locally defined. Link: https://docs.github.com/en/actions/learn-github-actions/reusing-workflows

Usage:

This workflow below should be copied into your repo at .github/workflows/R-CMD-check.yaml

# Workflow derived from https://github.com/rstudio/shiny-workflows
#
# NOTE: This Shiny team GHA workflow is overkill for most R packages.
# For most R packages it is better to use https://github.com/r-lib/actions
on:
  push:
    branches: [main, rc-**]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 8 * * 1' # every monday

name: Package checks

jobs:
  website:
    uses: rstudio/shiny-workflows/.github/workflows/website.yaml@v1
  routine:
    uses: rstudio/shiny-workflows/.github/workflows/routine.yaml@v1
  R-CMD-check:
    uses: rstudio/shiny-workflows/.github/workflows/R-CMD-check.yaml@v1

Note: Adjust the 8 in the schedule to match the number of letters in the package name to insert some time variance. This helps mitigate PAT rate limits when testing many packages on a schedule.

Workflows

There are three main reusable workflows to be used by packages in the shiny-verse

• website.yaml
  • This is a wrapper for building a {pkgdown} website and deploying it to the gh-pages branch of the repo.
  • Packages included in the DESCRIPTION field Config/Needs/website will also be installed
  • Parameters:
    • extra-packages: Installs extra packages not listed in the DESCRIPTION file to be installed. Link: https://github.com/r-lib/actions/tree/v2/setup-r-dependencies
    • cache-version: The cache key to be used. Link: https://github.com/r-lib/actions/tree/v2/setup-r-dependencies
    • pandoc-version: Sets the pandoc version to be installed. Link: https://github.com/r-lib/actions/tree/HEAD/setup-pandoc . Defaults to 3.x which installs a recent 3.x version of pandoc. (Similar behavior for 2.x.)
    • check-title: If set, will disable rmarkdown's check for having the vignette title and the document title match
• routine.yaml
  • Performs many common tasks for packages in the shiny-verse and commits them back to the repo
    • Check for url redirects in rc-v** branches
    • devtools::document()
    • devtools::build_readme() (if README.Rmd exists)
    • Calls yarn build and commits any changes in inst, srcts, and srcjs.
    • Checks code coverage with covr if codecov.yml exists
    • Checks for broken lints if .lintr exists
    • Calls yarn test
    • Checks for outdated staticimports
  • Packages included in the DESCRIPTION field Config/Needs/routine will also be installed
  • Parameters:
    • extra-packages, cache-version, pandoc-version: Same as in website.yaml
    • node-version: Version of node.js to install
• R-CMD-check.yaml
  • Performs R CMD check . on your package
  • Parameters:
    • extra-packages, cache-version, pandoc-version: Same as in website.yaml
    • extra-check-args: Arguments passed in addition to the default check args of https://github.com/r-lib/actions/blob/v2/check-r-package/
    • macOS: macOS runtime to use. Set to false to disable testing on macOS.
    • windows: windows runtime to use. Set to false to disable testing on Windows.
    • ubuntu: ubuntu runtime to use. To use more than one ubuntu value, send in a value separated by a space. For example, to test on ubuntu 18 and 20, use "ubuntu-18.04 ubuntu20.04". The first ubuntu value will be tested using the "devel" R version. Set to false to disable testing on Ubuntu.
    • staticimports: Determines if staticimports should display a warning message if the staticimports are out of date.
    • minimum-r-version: If provided, only R versions >= to minimum-r-version will be created in the matrix. Great for dependencies that will not install on earlier R versions.
    • rtools-35: If false, packages with a src folder will not test on Windows R 3.6 using rtools35.

Customization

There are a set of known files that can be run. The file just needs to exist to be run. No extra configuration necessary.

The files must exist in the .github/shiny-workflows/ folder. Such as .github/shiny-workflows/package-install.R.

Files:

• package-install.R / package-install.sh
  • This step is run in all workflows after R is installed, but before the local package dependencies are installed.
  • This script could be useful for installing custom dependencies
• website.R / website.sh
  • Run in website.yaml before the site is built
  • This script could be useful for copying assets to a directory
• routine.R / routine.sh
  • Run in routine.yaml. Runs before the local commits are pushed back to GitHub
  • This script could be useful for running some logic on a single OS and push the results back to GitHub
  • This script could be useful for running a test that needs to be performed once and not on every job of R-CMD-check.yaml

These scripts should be done for their side effects, such as copying files or installing dependencies.

For example, a common use case for using a shell script over an R script would be to install custom system dependencies. Since installation is usually OperatingSystem specific, you'll likely want to make use of System environment variables, such as $RUNNER_OS. Link: https://docs.github.com/en/actions/learn-github-actions/environment-variables

Example usage of package-install.sh:

if [ "$RUNNER_OS" == "macOS" ]; then
  brew install harfbuzz fribidi
fi

pkgdown setup

Typically when using pkgdown in a package, you run the command below to initalize all necessary configs.

# Init pkgdown webs
usethis::use_pkgdown_github_pages()

However, we will need to remove the GHA workflow file created, as we will use the website.yaml reusable shiny-workflow.

# Remove pkgdown workflow file; (Using reusable shiny-workflow)
unlink(".github/workflows/pkgdown.yaml")

Where to find help

If your build fails and you are unsure of why, please visit https://github.com/r-lib/actions#where-to-find-help for more debugging tips. If you feel it is an error done by shiny-workflows, please submit an issue: https://github.com/rstudio/shiny-workflows/issues/new

Additional resources

• r-lib/actions
• GitHub Actions for R, Jim Hester's talk at rstudio::conf 2020. Recording, slidedeck.
• GitHub Actions advent calendar a series of blogposts by Edward Thomson, one of the GitHub Actions product managers highlighting features of GitHub Actions.
• GitHub Actions with R - a short online book about using GitHub Actions with R, produced as part of the rOpenSci OzUnconf.
• Awesome Actions - a curated list of custom actions. Note many of these are from early in the GitHub Actions beta and may no longer work.

Common questions

1. Why are my builds failing on macOS?
   Please double check that their are no required dependencies stated in the log during installation. If there is an unmet dependency, please make an issue so that other repos may utilize this knowledge: https://github.com/rstudio/shiny-workflows/issues/new
2. What if my website is custom?
   It is ok to comment the website job in your workflow file. When the time comes that you can use the standardised {pkgdown} workflow, feel free to uncomment the website job.

shiny-workflow development

Adopting a feature

Reasons to consider a feature:

• If more than two repos needs custom work, it should be considered.
• If all other repos could benefit from an installation step, even if they are currently not utilized. (Ex: phantomJS, tinytex)

Reasons to NOT consider a feature:

• Trying to appease a single repo. General response: The repo can run more compute cycles / jobs to meet their needs
• The feature imposes behavior that no other repos are performing or willing to adopt. Ex: Automatically setting the package version in package.json

Updates to workflows or actions

If updates are made to the workflows, the v1 tag must be (forcefully) moved forward to the latest value within the rstudio/shiny-workflows. To do this, run:

git tag -f v1
git push origin --tags -f

License

All examples in this repository are published with the CC0 license.