Skip to content

GitHub Actions setup

Source: R/github-actions.R
github_actions.Rd

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, such as:

  • Run R CMD check on various operating systems and R versions

  • Build and deploy a pkgdown site

  • Determine test coverage

This family of functions

  • Adds the necessary configuration files and lists them in .Rbuildignore

  • Provides the markdown to insert a badge into your README

Usage

use_github_actions()

use_github_actions_badge(name = "R-CMD-check.yaml", repo_spec = NULL)

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

use_github_action_check_release(
  save_as = "R-CMD-check.yaml",
  ref = NULL,
  ignore = TRUE,
  open = FALSE
)

use_github_action_check_standard(
  save_as = "R-CMD-check.yaml",
  ref = NULL,
  ignore = TRUE,
  open = FALSE
)

use_github_action_pr_commands(
  save_as = "pr-commands.yaml",
  ref = NULL,
  ignore = TRUE,
  open = FALSE
)

Arguments

name

For use_github_action(): Name of one of the example workflows from https://github.com/r-lib/actions/tree/v2/examples. Examples: "pkgdown", "check-standard.yaml".

For use_github_actions_badge(): Name of the workflow's YAML configuration file. Examples: "R-CMD-check", "R-CMD-check.yaml".

If name has no extension, we assume it's .yaml.

repo_spec

Optional GitHub repo specification in this form: owner/repo. This can usually be inferred from the GitHub remotes of active project.

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.

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.

use_github_actions()

Configures a basic R CMD check workflow on GitHub Actions by adding a standard R-CMD-check.yaml file to the .github/workflows directory of the active project. This is actually just an alias for use_github_action_check_release().

use_github_actions_badge()

Generates a GitHub Actions badge and that's all. It does not configure a workflow. This exists mostly for internal use in the other functions documented here.

use_github_action()

Configures an individual, specific GitHub Actions workflow, either one of the examples from r-lib/actions/examples or a custom workflow given by the url parameter.

Used internally to power all the other GitHub Actions functions, but it can also be called directly by the user.

use_github_action_check_release()

This entry-level, bare-minimum workflow installs the latest release of R (on a current distribution of Linux) and runs R CMD check via the rcmdcheck package.

use_github_action_check_standard()

This workflow runs R CMD check via the rcmdcheck package on the three major operating systems (Linux, macOS, and Windows) on the latest release of R and on R-devel. This workflow is appropriate for a package that is (or aspires to be) on CRAN or Bioconductor.

use_github_action_pr_commands()

This workflow enables the use of two R-specific commands in pull request issue comments:

See also

Examples

if (FALSE) {
use_github_actions()

use_github_action_check_standard()

use_github_action("pkgdown")
}