use_github_action {usethis}

Set up a GitHub Actions workflow

Description

Sets up continuous integration (CI) for an R package that is developed on GitHub using GitHub Actions. CI can be used to trigger various operations for each push or pull request, e.g. running ⁠R CMD check⁠ or building and deploying a pkgdown site.

Workflows

There are four particularly important workflows that are used by many packages:

• check-standard: Run ⁠R CMD check⁠ using R-latest on Linux, Mac, and Windows, and using R-devel and R-oldrel on Linux. This is a good baseline if you plan on submitting your package to CRAN.

• test-coverage: Compute test coverage and report to https://about.codecov.io by calling covr::codecov().

• pkgdown: Automatically build and publish a pkgdown website. But we recommend instead calling use_pkgdown_github_pages() which performs other important set up.

• pr-commands: Enables the use of two R-specific commands in pull request issue comments: ⁠/document⁠ to run roxygen2::roxygenise() and ⁠/style⁠ to run styler::style_pkg(). Both will update the PR with any changes once they're done.

If you call use_github_action() without arguments, you'll be prompted to pick from one of these. Otherwise you can see a complete list of possibilities provided by r-lib at https://github.com/r-lib/actions/tree/v2/examples, or you can supply your own url to use any other workflow.

Usage

use_github_action(
  name = NULL,
  ref = NULL,
  url = NULL,
  save_as = NULL,
  readme = NULL,
  ignore = TRUE,
  open = FALSE,
  badge = NULL
)

Arguments

name

For use_github_action(): Name of one of the example workflow from https://github.com/r-lib/actions/tree/v2/examples (with or without extension), e.g. "pkgdown", "check-standard.yaml".

If the name starts with ⁠check-⁠, save_as will default to R-CMD-check.yaml and badge default to TRUE.

ref

Desired Git reference, usually the name of a tag ("v2") or branch ("main"). Other possibilities include a commit SHA ("d1c516d") or "HEAD" (meaning "tip of remote's default branch"). If not specified, defaults to the latest published release of r-lib/actions (https://github.com/r-lib/actions/releases).

url

The full URL to a .yaml file on GitHub. See more details in use_github_file().

save_as

Name of the local workflow file. Defaults to name or fs::path_file(url) for use_github_action(). Do not specify any other part of the path; the parent directory will always be .github/workflows, within the active project.

readme

The full URL to a README file that provides more details about the workflow. Ignored when url is NULL.

ignore

Should the newly created file be added to .Rbuildignore?

open

Open the newly created file for editing? Happens in RStudio, if applicable, or via utils::file.edit() otherwise.

badge

Should we add a badge to the README?

Examples

## Not run: 
use_github_action()

use_github_action_check_standard()

use_github_action("pkgdown")

## End(Not run)