Sets up continuous integration (CI) for an R package that is developed on
GitHub using GitHub Actions (GHA). 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.
Core workflows
There are three particularly important workflows that are used by many packages:
check-standard
: RunR 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 callingcovr::codecov()
.pkgdown
: Automatically build and publish a pkgdown website. But we recommend instead callinguse_pkgdown_github_pages()
, which sets up thepkgdown
workflow AND performs other important set up.
If you call use_github_action()
without arguments, you'll get a choice of
some recommended workflows. Otherwise you can specify the name of any
workflow provided by r-lib/actions
, which are listed at
https://github.com/r-lib/actions/tree/v2/examples. Finally you can supply
the full url
to any workflow on GitHub.
Other workflows
Other specific workflows are worth mentioning:
format-suggest
orformat-check
from Air:Either of these workflows is a great way to keep your code well-formatted once you adopt Air in a project (possibly via
use_air()
). Here's how to set them up:use_github_action(url = "https://github.com/posit-dev/setup-air/blob/main/examples/format-suggest.yaml") use_github_action(url = "https://github.com/posit-dev/setup-air/blob/main/examples/format-check.yaml")
Learn more from Air's documentation of its GHA integrations.
pr-commands
:Enables the use of two R-specific commands in pull request issue comments:
/document
to runroxygen2::roxygenise()
and/style
to runstyler::style_pkg()
. Both will update the PR with any changes once they're done.We don't recommend new adoption of the
pr-commands
workflow. For code formatting, the Air workflows described above are preferred. We plan to re-implement documentation updates using a similar approach.
Usage
use_github_action(
name = NULL,
ref = NULL,
url = NULL,
save_as = NULL,
readme = NULL,
ignore = TRUE,
open = FALSE,
badge = NULL
)
Arguments
- name
Name of one of the example workflows from https://github.com/r-lib/actions/tree/v2/examples (with or without extension), e.g.
"pkgdown"
,"check-standard.yaml"
.If the
name
starts withcheck-
,save_as
defaults toR-CMD-check.yaml
andbadge
defaults toTRUE
.- 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 ofr-lib/actions
(https://github.com/r-lib/actions/releases).- url
The full URL to a
.yaml
file on GitHub. See more details inuse_github_file()
.- save_as
Name of the local workflow file. Defaults to
name
orfs::path_file(url)
. 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 whenurl
isNULL
.- 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
?