use_github_action: Set up a GitHub Actions workflow

In usethis: Automate Package and Project Setup

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)

usethis documentation built on Sept. 11, 2024, 5:29 p.m.