Package 'tic'

Description

Provides a way to describe common build and deployment workflows for R-based projects: packages, websites (e.g. blogdown, pkgdown), or data processing (e.g. research compendia). The recipe is described independent of the continuous integration tool used for processing the workflow (e.g. 'GitHub Actions' or 'Circle CI'). This package has been peer-reviewed by rOpenSci (v0.3.0.9004).

Details

The use_tic() function prepares a code repository for use with this package. See DSL for an overview of tic's domain-specific language for defining stages and steps, step_hello_world() and the links therein for available steps, and macro for an overview over the available macros that bundle several steps.

Author(s)

Maintainer: Patrick Schratz [email protected] (ORCID)

Authors:

• Kirill Müller (ORCID)

• Mika Braginsky [email protected]

• Karthik Ram [email protected]

• Jeroen Ooms [email protected]

Other contributors:

• Max Held (Max reviewed the package for ropensci, see <https://github.com/ropensci/software-review/issues/305>) [reviewer]

• Anna Krystalli (Anna reviewed the package for ropensci, see <https://github.com/ropensci/software-review/issues/305>) [reviewer]

• Laura DeCicco (Laura reviewed the package for ropensci, see <https://github.com/ropensci/software-review/issues/305>) [reviewer]

• rOpenSci [funder]

See Also

Useful links:

• https://github.com/ropensci/tic

• Report bugs at https://github.com/ropensci/tic/issues

Description

base64serialize() converts an R object into a string suitable for storing in an environment variable. Use this function for encoding entire R objects (such as OAuth tokens).

base64unserialize() is the inverse operation to base64serialize(). Use this function in your tic.R to access the R object previously encoded by base64serialize().

Usage

base64serialize(x, compression = "gzip")

base64unserialize(x, compression = "gzip")

Arguments

Examples

serial <- base64serialize(1:10)
base64unserialize(serial)

Description

Functions that return environment settings that describe the CI environment. The value is retrieved only once and then cached.

ci_get_branch(): Returns the current branch. Returns nothing if operating on a tag.

ci_is_tag(): Returns the current tag name. Returns nothing if a branch is selected.

ci_get_slug(): Returns the repo slug in the format user/repo or org/repo

ci_get_build_number(): Returns the CI build number.

ci_get_build_url(): Returns the URL of the current build.

ci_get_commit(): Returns the SHA1 of the current commit.

ci_get_env(): Return an environment or configuration variable.

ci_is_env(): Checks if an environment or configuration variable is set to a particular value.

ci_has_env(): Checks if an environment or configuration variable is set to any value.

ci_can_push(): Checks if push deployment is possible. Always true for local environments, CI environments require an environment variable (by default TIC_DEPLOY_KEY).

ci_is_interactive(): Returns whether the current build is run interactively or not. Global setup operations shouldn't be run on interactive CIs.

ci_cat_with_color(): Colored output targeted to the CI log. The code argument can be an unevaluated call to a crayon function, the style will be applied even if it normally wouldn't be.

ci_on_circle(): Are we running on Circle CI?

ci_on_ghactions(): Are we running on GitHub Actions?

ci(): Return the current CI environment

Usage

ci_get_branch()

ci_is_tag()

ci_get_slug()

ci_get_build_number()

ci_get_build_url()

ci_get_commit()

ci_get_env(env)

ci_is_env(env, value)

ci_has_env(env)

ci_can_push(private_key_name = "TIC_DEPLOY_KEY")

ci_is_interactive()

ci_cat_with_color(code)

ci_on_circle()

ci_on_ghactions()

ci()

Arguments

Description

add_package_checks() has been replaced by do_package_checks().

Usage

add_package_checks(
  ...,
  warnings_are_errors = NULL,
  notes_are_errors = NULL,
  args = c("--no-manual", "--as-cran"),
  build_args = "--force",
  error_on = "warning",
  repos = repo_default(),
  timeout = Inf
)

Arguments

Description

do_blogdown() adds default steps related to package checks to the "install", "before_deploy", "script" and "deploy" stages.

1. step_install_deps() in the "install" stage

2. blogdown::install_hugo() in the "install" stage to install the latest version of HUGO.

3. step_session_info() in the "install" stage.

4. step_setup_ssh() in the "before_deploy" to setup the upcoming deployment (if deploy is set),

5. step_setup_push_deploy() in the "before_deploy" stage (if deploy is set),

6. step_build_blogdown() in the "deploy" stage, forwarding all ... arguments.

7. step_do_push_deploy() in the "deploy" stage.

By default, the ⁠public/⁠ directory is deployed to the gh-pages branch, keeping the history. If the output directory of your blog/theme is not "public" you need to change the "path" argument.

Usage

do_blogdown(
  ...,
  deploy = NULL,
  orphan = FALSE,
  checkout = TRUE,
  path = "public",
  branch = "gh-pages",
  remote_url = NULL,
  commit_message = NULL,
  commit_paths = ".",
  force = FALSE,
  private_key_name = "TIC_DEPLOY_KEY",
  cname = NULL
)

Arguments

See Also

Other macros: do_bookdown(), do_drat(), do_package_checks(), do_pkgdown(), do_readme_rmd(), list_macros()

Examples

## Not run: 
dsl_init()

do_blogdown()

dsl_get()

## End(Not run)

Description

do_bookdown() adds default steps related to package checks to the "install", "before_deploy", "script" and "deploy" stages.

1. step_install_deps() in the "install" stage

2. step_session_info() in the "install" stage.

3. step_setup_ssh() in the "before_deploy" to setup the upcoming deployment (if deploy is set),

4. step_setup_push_deploy() in the "before_deploy" stage (if deploy is set),

5. step_build_bookdown() in the "deploy" stage, forwarding all ... arguments.

6. step_do_push_deploy() in the "deploy" stage.

By default, the ⁠_book/⁠ directory is deployed to the gh-pages branch, keeping the history.

Usage

do_bookdown(
  ...,
  deploy = NULL,
  orphan = FALSE,
  checkout = TRUE,
  path = "_book",
  branch = "gh-pages",
  remote_url = NULL,
  commit_message = NULL,
  commit_paths = ".",
  force = FALSE,
  private_key_name = "TIC_DEPLOY_KEY",
  cname = NULL
)

Arguments

See Also

Other macros: do_blogdown(), do_drat(), do_package_checks(), do_pkgdown(), do_readme_rmd(), list_macros()

Examples

## Not run: 
dsl_init()

do_bookdown()

dsl_get()

## End(Not run)

Description

do_drat() builds and deploys R packages to a drat repository and adds default steps to the "install", "before_deploy" and "deploy" stages:

1. step_setup_ssh() in the "before_deploy" to setup the upcoming deployment

2. step_setup_push_deploy() in the "before_deploy" stage (if deploy is set),

3. step_add_to_drat() in the "deploy"

4. step_do_push_deploy() in the "deploy" stage.

Usage

do_drat(
  repo_slug = NULL,
  orphan = FALSE,
  checkout = TRUE,
  path = "~/git/drat",
  branch = NULL,
  remote_url = NULL,
  commit_message = NULL,
  commit_paths = ".",
  force = FALSE,
  private_key_name = "TIC_DEPLOY_KEY",
  deploy_dev = FALSE
)

Arguments

Deployment

Deployment can only happen to the default repo branch (usually "master") or gh-pages branch because the GitHub Pages functionality from GitHub is used to access the drat repository later on. You need to enable this functionality when creating the drat repository on GitHub via ⁠Settings -> GitHub pages⁠ and set it to the chosen setting here.

To build and deploy Windows and macOS binaries, builds with deployment permissions need to be triggered. Have a look at https://docs.ropensci.org/tic/articles/deployment.html for more information and instructions.

See Also

Other macros: do_blogdown(), do_bookdown(), do_package_checks(), do_pkgdown(), do_readme_rmd(), list_macros()

Examples

## Not run: 
dsl_init()

do_drat()

dsl_get()

## End(Not run)

Description

do_package_checks() adds default steps related to package checks to the "before_install", "install", "script" and "after_success" stages:

This macro is only available for R packages.

1. step_install_deps() in the "install" stage, using the repos argument.

2. step_session_info() in the "install" stage.

3. step_rcmdcheck() in the "script" stage, using the warnings_are_errors, notes_are_errors, args, and build_args arguments.

4. A call to covr::codecov() in the "after_success" stage (only if the codecov flag is set)

Usage

do_package_checks(
  ...,
  codecov = !ci_is_interactive(),
  warnings_are_errors = NULL,
  notes_are_errors = NULL,
  args = NULL,
  build_args = NULL,
  error_on = "warning",
  repos = repo_default(),
  dependencies = TRUE,
  timeout = Inf,
  check_dir = "check"
)

Arguments

See Also

Other macros: do_blogdown(), do_bookdown(), do_drat(), do_pkgdown(), do_readme_rmd(), list_macros()

Examples

dsl_init()

do_package_checks()

dsl_get()

Description

do_pkgdown() builds and optionally deploys a pkgdown site and adds default steps to the "install", "before_deploy" and "deploy" stages:

1. step_install_deps() in the "install" stage

2. step_session_info() in the "install" stage.

3. step_setup_ssh() in the "before_deploy" to setup the upcoming deployment (if deploy is set and only on GitHub Actions),

4. step_setup_push_deploy() in the "before_deploy" stage (if deploy is set),

5. step_build_pkgdown() in the "deploy" stage, forwarding all ... arguments.

6. step_do_push_deploy() in the "deploy" stage.

By default, the ⁠docs/⁠ directory is deployed to the gh-pages branch, keeping the history.

Usage

do_pkgdown(
  ...,
  deploy = NULL,
  orphan = FALSE,
  checkout = TRUE,
  path = "docs",
  branch = "gh-pages",
  remote_url = NULL,
  commit_message = NULL,
  commit_paths = ".",
  force = FALSE,
  private_key_name = "TIC_DEPLOY_KEY"
)

Arguments

See Also

Other macros: do_blogdown(), do_bookdown(), do_drat(), do_package_checks(), do_readme_rmd(), list_macros()

Examples

## Not run: 
dsl_init()

do_pkgdown()

dsl_get()

## End(Not run)

Description

do_readme_rmd() renders an R Markdown README and deploys the rendered README.md file to Github. It adds default steps to the "before_deploy" and "deploy" stages:

1. step_setup_ssh() in the "before_deploy" to setup the upcoming deployment

2. step_setup_push_deploy() in the "before_deploy" stage

3. rmarkdown::render() in the "deploy" stage

4. step_do_push_deploy() in the "deploy" stage.

Usage

do_readme_rmd(
  checkout = TRUE,
  remote_url = NULL,
  commit_message = NULL,
  force = FALSE,
  private_key_name = "TIC_DEPLOY_KEY"
)

Arguments

See Also

Other macros: do_blogdown(), do_bookdown(), do_drat(), do_package_checks(), do_pkgdown(), list_macros()

Examples

## Not run: 
dsl_init()

do_readme_rmd()

dsl_get()

## End(Not run)

Description

Functions to define stages and their constituent steps. The macros combine several steps and assign them to relevant stages. See dsl_get() for functions to access the storage for the stages and their steps.

get_stage() returns a TicStage object for a stage given by name. This function can be called directly in the tic.R configuration file, which is processed by dsl_load().

add_step() adds a step to a stage, see step_hello_world() and the links therein for available steps.

add_code_step() is a shortcut for add_step(step_run_code(...)).

Usage

get_stage(name)

add_step(stage, step)

add_code_step(stage, call = NULL, prepare_call = NULL)

Arguments

Examples

dsl_init()

get_stage("script")

get_stage("script") %>%
  add_step(step_hello_world())

get_stage("script")

get_stage("script") %>%
  add_code_step(print("Hi!"))

get_stage("script")

Description

tic works in a declarative way, centered around the tic.R file created by use_tic(). This file contains the definition of the steps to be run in each stage: calls to get_stage() and add_step(), or macros like do_package_checks().

Normally, this file is never executed directly. Running these functions in an interactive session will not carry out the respective actions. Instead, a description of the code that would have been run is printed to the console. Edit tic.R to configure your CI builds. See vignette("build-lifecycle", package = "tic") for more details.

Usage

dsl_get()

dsl_load(path = "tic.R", force = FALSE, quiet = FALSE)

dsl_init(quiet = FALSE)

Arguments

Details

Stages and steps defined using tic's DSL are stored in an internal object in the package. The stages are accessible through dsl_get(). When running the stages, by default a configuration defined in the tic.R file is loaded with dsl_load(). See use_tic() for setting up a tic.R file.

For interactive tests, an empty storage can be initialized with dsl_init(). This happens automatically the first time dsl_get() is called (directly or indirectly).

Value

A named list of opaque stage objects with a "class" attribute and a corresponding print() method for pretty output. Use the high-level get_stage() and add_step() functions to configure, and the stages functions to run.

Examples

## Not run: 
dsl_init()
dsl_get()

dsl_load(system.file("templates/package/tic.R", package = "tic"))
dsl_load(system.file("templates/package/tic.R", package = "tic"),
  force =
    TRUE
)
dsl_get()

## End(Not run)

Description

Encrypts the supplied value using libsodium and adds it as a secret to the given GitHub repository. Secrets can be be used in GitHub Action runs as environment variables. A common use case is to encrypt Personal Access Tokens (PAT) or API keys.

This is the same as adding a secret manually in GitHub via "Settings" -> "Secrets" -> "New repository secret"

Usage

gha_add_secret(
  secret,
  name,
  repo_slug = NULL,
  remote = "origin",
  visibility = "all",
  selected_repositories = NULL
)

Arguments

Examples

## Not run: 
gha_add_secret("supersecret", name = "MY_SECRET", repo = "ropensci/tic")

## End(Not run)

Description

• auth_github(): Creates a GITHUB_TOKEN and asks to store it in your .Renviron file.

• get_owner(): Returns the owner of a Github repo.

• get_repo(): Returns the repo name of a Github repo for a given remote.

• get_repo_slug(): Returns the repo slug of a Github repo (⁠<owner>/<repo>⁠).

Usage

auth_github()

get_owner(remote = "origin")

get_user()

get_repo(remote = "origin")

get_repo_slug(remote = "origin")

Arguments

Description

github_repo() returns the true repository name as string.

Retrieves metadata about a Git repository from GitHub.

github_info() returns a list as obtained from the GET "/repos/:repo" API.

Usage

github_repo(
  path = usethis::proj_get(),
  info = github_info(path, remote = remote),
  remote = "origin"
)

github_info(path = usethis::proj_get(), remote = "origin")

uses_github(path = usethis::proj_get())

Arguments

Description

Lists available macro functions of the tic package.

Usage

list_macros()

Value

character

See Also

Other macros: do_blogdown(), do_bookdown(), do_drat(), do_package_checks(), do_pkgdown(), do_readme_rmd()

Description

The DSL offers a fine-grained interface to the individual stages of a CI run. Macros are tic's way of adding several related steps to the relevant stages. All macros use the do_ prefix.

The do_package_checks() macro adds default checks for R packages, including installation of dependencies and running a test coverage analysis.

The do_pkgdown() macro adds the necessary steps for building and deploying pkgdown documentation for a package.

The do_blogdown() macro adds the necessary steps for building and deploying a blogdown blog.

The do_bookdown() macro adds the necessary steps for building and deploying a bookdown book.

The do_drat() macro adds the necessary steps for building and deploying a drat repository to host R package sources.

The do_readme_rmd() macro renders an R Markdown README and deploys the rendered README.md file to Github.

Description

Run the prepare() method for all defined steps for which the check() method returns TRUE.

Usage

prepare_all_stages(stages = dsl_load())

Arguments

See Also

TicStep

Other runners: run_all_stages(), run_stage()

Description

These functions can be used as convenient shortcuts for the repos argument to e.g. do_package_checks() and step_install_deps().

repo_default() returns the value of the "repos" option, or repo_cloud() if the option is not set.

repo_cloud() returns RStudio's CRAN mirror.

repo_cran() returns the master CRAN repo.

repo_bioc() returns Bioconductor repos from remotes::bioc_install_repos(), in addition to the default repo.

Usage

repo_default()

repo_cloud()

repo_cran()

repo_bioc(base = repo_default())

Arguments

Description

Runs predefined stages similarly to the chosen CI provider. The run aborts on error, the after_failure stage is never run.

Usage

run_all_stages(stages = dsl_load())

Arguments

Details

The stages are run in the following order:

1. before_install()

2. install()

3. after_install()

4. before_script()

5. script()

6. after_success()

7. before_deploy()

8. deploy()

9. after_deploy()

10. after_script()

See Also

Other runners: prepare_all_stages(), run_stage()

Description

Run the run_all() method for all defined steps of a stage for which the check() method returns TRUE.

Usage

run_stage(name, stages = dsl_load())

Arguments

See Also

TicStep

Other runners: prepare_all_stages(), run_all_stages()

Description

SSH key helpers

Usage

github_add_key(
  pubkey,
  repo = get_repo(remote),
  user = get_user(),
  title = "ghactions",
  remote = "origin",
  check_role = TRUE
)

check_admin_repo(owner, user, repo)

get_role_in_repo(owner, user, repo)

get_public_key(key)

encode_private_key(key)

check_private_key_name(string)

Arguments

Description

Stages available in the CI provider, for which shortcuts have been defined. All these functions call run_stage() with the corresponding stage name.

Usage

before_install(stages = dsl_load())

install(stages = dsl_load())

after_install(stages = dsl_load())

before_script(stages = dsl_load())

script(stages = dsl_load())

after_success(stages = dsl_load())

after_failure(stages = dsl_load())

before_deploy(stages = dsl_load())

deploy(stages = dsl_load())

after_deploy(stages = dsl_load())

after_script(stages = dsl_load())

Arguments

Description

Builds a package (binary on OS X or Windows) and inserts it into an existing drat repository via drat::insertPackage().

Usage

step_add_to_drat(repo_slug = NULL, deploy_dev = FALSE)

Arguments

See Also

Other steps: step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

dsl_init()

get_stage("script") %>%
  add_step(step_add_to_drat())

dsl_get()

Description

Adds a host name to the ⁠~/.ssh/known_hosts⁠ file to allow subsequent SSH access. Requires ssh-keyscan on the system PATH.

Usage

step_add_to_known_hosts(host = "github.com")

Arguments

See Also

Other steps: step_add_to_drat(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

dsl_init()

get_stage("before_deploy") %>%
  add_step(step_add_to_known_hosts("gitlab.com"))

dsl_get()

Description

Build a Blogdown site using blogdown::build_site().

Usage

step_build_blogdown(...)

Arguments

Examples

dsl_init()

get_stage("script") %>%
  add_step(step_build_blogdown("."))

dsl_get()

Description

Build a bookdown book using bookdown::render_book().

Usage

step_build_bookdown(...)

Arguments

Examples

dsl_init()

get_stage("script") %>%
  add_step(step_build_bookdown("."))

dsl_get()

Description

Builds package documentation with the pkgdown package. Calls pkgdown::clean_site() and then pkgdown::build_site(...).

Usage

step_build_pkgdown(...)

Arguments

See Also

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

dsl_init()

get_stage("script") %>%
  add_step(step_build_pkgdown())

dsl_get()

Description

Commits and pushes to a repo prepared by step_setup_push_deploy().

Deployment usually requires setting up SSH keys with use_tic().

Usage

step_do_push_deploy(
  path = ".",
  commit_message = NULL,
  commit_paths = ".",
  force = FALSE
)

Arguments

Details

It is highly recommended to restrict the set of files touched by the deployment with the commit_paths argument: this step assumes that it can freely overwrite all changes to all files below commit_paths, and will not warn in case of conflicts.

To mitigate conflicts race conditions to the greatest extent possible, the following strategy is used:

• The changes are committed to the branch

• Before pushing, new commits are fetched, and the changes are cherry-picked on top of the new commits

If no new commits were pushed after the CI run has started, this strategy is equivalent to committing and pushing. In the opposite case, if the remote repo has new commits, the deployment is safely applied to the current tip.

See Also

Other deploy steps: step_push_deploy(), step_setup_push_deploy()

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

## Not run: 
dsl_init()

# Deployment only works if a companion step_setup_push_deploy() is added
get_stage("deploy") %>%
  add_step(step_setup_push_deploy(path = "docs", branch = "gh-pages")) %>%
  add_step(step_build_pkgdown())

if (rlang::is_installed("git2r") && git2r::in_repository()) {
  get_stage("deploy") %>%
    add_step(step_do_push_deploy(path = "docs"))
}

dsl_get()

## End(Not run)

Description

The simplest step possible: prints "Hello, world!" to the console when run, does not require any preparation. This step may be useful to test a tic setup or as a starting point when implementing a custom step.

Usage

step_hello_world()

See Also

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

dsl_init()

get_stage("script") %>%
  add_step(step_hello_world())

dsl_get()

Description

These steps are useful if your CI run needs additional packages. Usually they are declared as dependencies in your DESCRIPTION, but it is also possible to install dependencies manually. By default, binary versions of packages are installed if possible, even if the CRAN version is ahead.

A step_install_deps() step installs all package dependencies declared in DESCRIPTION, using pak::local_install_dev_deps(). This includes upgrading outdated packages.

This step can only be used if a DESCRIPTION file is present in the repository root.

A step_install_cran() step installs one package from CRAN via install.packages(), but only if it's not already installed.

A step_install_github() step installs one or more packages from GitHub via pak::pkg_install(), the packages are only installed if their GitHub version is different from the locally installed version.

Usage

step_install_deps(dependencies = TRUE)

step_install_cran(package = NULL, ...)

step_install_github(repo = NULL, ...)

Arguments

See Also

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

dsl_init()

get_stage("install") %>%
  add_step(step_install_deps())

dsl_get()
dsl_init()

get_stage("install") %>%
  add_step(step_install_cran("magick"))

dsl_get()
dsl_init()

get_stage("install") %>%
  add_step(step_install_github("rstudio/gt"))

dsl_get()

Description

Writes a private SSH key encoded in an environment variable to a file in ⁠~/.ssh⁠. Only run in non-interactive settings and if the environment variable exists and is non-empty. use_ghactions_deploy() and use_tic() functions encode a private key as an environment variable for use with this function.

Usage

step_install_ssh_keys(private_key_name = "TIC_DEPLOY_KEY")

Arguments

See Also

use_tic(), use_ghactions_deploy()

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_push_deploy(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

dsl_init()

get_stage("before_deploy") %>%
  add_step(step_install_ssh_keys())

dsl_get()

Description

Clones a repo, initializes author information, sets up remotes, commits, and pushes. Combines step_setup_push_deploy() with checkout = FALSE and a suitable orphan argument, and step_do_push_deploy().

Deployment usually requires setting up SSH keys with use_tic().

Usage

step_push_deploy(
  path = ".",
  branch = NULL,
  remote_url = NULL,
  commit_message = NULL,
  commit_paths = ".",
  force = FALSE
)

Arguments

Details

Setup and deployment are combined in one step, the files to be deployed must be prepared in a previous step. This poses some restrictions on how the repository can be initialized, in particular for a nonstandard path argument only orphan = TRUE can be supported (and will be used).

For more control, create two separate steps with step_setup_push_deploy() and step_do_push_deploy(), and create the files to be deployed in between these steps.

See Also

Other deploy steps: step_do_push_deploy(), step_setup_push_deploy()

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

## Not run: 
dsl_init()

get_stage("script") %>%
  add_step(step_push_deploy(commit_paths = c("NAMESPACE", "man")))

dsl_get()

## End(Not run)

Description

Check a package using rcmdcheck::rcmdcheck(), which ultimately calls ⁠R CMD check⁠.

Usage

step_rcmdcheck(
  ...,
  warnings_are_errors = NULL,
  notes_are_errors = NULL,
  args = NULL,
  build_args = NULL,
  error_on = "warning",
  repos = repo_default(),
  timeout = Inf,
  check_dir = "check"
)

Arguments

Updating of (dependency) packages

Packages shipped with the R-installation will not be updated as they will be overwritten by the R-installer in each build. If you want these package to be updated, please add the following step to your workflow: add_code_step(remotes::update_packages("<pkg>")).

Examples

dsl_init()

get_stage("script") %>%
  add_step(step_rcmdcheck(error_on = "note", repos = repo_bioc()))

dsl_get()

Description

Captures the expression and executes it when running the step. An optional preparatory expression can be provided that is executed during preparation. If the top-level expression is a qualified function call (of the format package::fun()), the package is installed during preparation.

Usage

step_run_code(call = NULL, prepare_call = NULL)

Arguments

See Also

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

dsl_init()

get_stage("install") %>%
  add_step(step_run_code(update.packages(ask = FALSE)))

# Will install covr from CRAN during preparation:
get_stage("after_success") %>%
  add_code_step(covr::codecov())

dsl_get()

Description

Prints out the package information of the current session via sessioninfo::session_info().

Usage

step_session_info()

See Also

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

dsl_init()

get_stage("install") %>%
  add_step(step_session_info())

dsl_get()

Description

Clones a repo, inits author information, and sets up remotes for a subsequent step_do_push_deploy().

Usage

step_setup_push_deploy(
  path = ".",
  branch = NULL,
  orphan = FALSE,
  remote_url = NULL,
  checkout = TRUE
)

Arguments

See Also

Other deploy steps: step_do_push_deploy(), step_push_deploy()

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_session_info(), step_setup_ssh(), step_test_ssh(), step_write_text_file()

Examples

## Not run: 
dsl_init()

get_stage("deploy") %>%
  add_step(step_setup_push_deploy(path = "docs", branch = "gh-pages")) %>%
  add_step(step_build_pkgdown())

# This example needs a Git repository
if (rlang::is_installed("git2r") && git2r::in_repository()) {
  # Deployment only works if a companion step_do_push_deploy() is added
  get_stage("deploy") %>%
    add_step(step_do_push_deploy(path = "docs"))
}

dsl_get()

## End(Not run)

Description

Adds to known hosts, installs private key, and tests the connection. Chaining step_install_ssh_keys(), step_add_to_known_hosts() and step_test_ssh(). use_tic() encodes a private key as an environment variable for use with this function.

Usage

step_setup_ssh(
  private_key_name = "TIC_DEPLOY_KEY",
  host = "github.com",
  url = paste0("git@", host),
  verbose = ""
)

Arguments

See Also

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_test_ssh(), step_write_text_file()

Examples

dsl_init()

get_stage("script") %>%
  add_step(step_setup_ssh(host = "gitlab.com"))

dsl_get()

Description

Establishes an SSH connection. This step doesn't fail if the connection cannot be established, but prints verbose output by default. It is useful for troubleshooting deployment problems.

Usage

step_test_ssh(
  url = "[email protected]",
  verbose = "",
  private_key_name = "TIC_DEPLOY_KEY"
)

Arguments

See Also

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_write_text_file()

Examples

dsl_init()

get_stage("script") %>%
  add_step(step_test_ssh(verbose = "-vvv"))

dsl_get()

Description

Creates a text file with arbitrary contents

Usage

step_write_text_file(..., path)

Arguments

See Also

Other steps: step_add_to_drat(), step_add_to_known_hosts(), step_build_pkgdown(), step_do_push_deploy(), step_hello_world(), step_install_pkg, step_install_ssh_keys(), step_push_deploy(), step_run_code(), step_session_info(), step_setup_push_deploy(), step_setup_ssh(), step_test_ssh()

Examples

dsl_init()

get_stage("script") %>%
  add_step(step_write_text_file("Hi!", path = "hello.txt"))

dsl_get()

Description

Override this class to create a new step.

Methods

Public methods

• TicStep$new()

• TicStep$run()

• TicStep$prepare()

• TicStep$check()

Method new()

Create a TicStep object.

Usage

TicStep$new()

Method run()

This method must be overridden, it is called when running the stage to which a step has been added.

Usage

TicStep$run()

Method prepare()

This is just a placeholder. This method is called when preparing the stage to which a step has been added. It auto-install all packages which are needed for a certain step. For example, step_build_pkgdown() requires the pkgdown package.

For add_code_step(), it autodetects any package calls in the form of pkg::fun and tries to install these packages from CRAN. If a steps prepare_call is not empty, the ⁠$prepare⁠ method is skipped for this step. This can be useful if a package should be installed from non-standard repositories, e.g. from GitHub.

Usage

TicStep$prepare()

Method check()

This method determines if a step is prepared and run. Return FALSE if conditions for running this step are not met.

Usage

TicStep$check()

Description

Updates YAML templates to their latest versions. Currently only GitHub Actions and Circle CI templates are supported.

Usage

update_yml(template_in = NULL, template_out = NULL)

Arguments

Details

By default all workflow files starting with tic are matched. This means that you can have multiple YAML files with update support, e.g. "tic.yml" and "tic-db.yml".

Formatting requirements of tic YAML templates

To ensure that updating of tic templates works, ensure the following points:

• Your template contains the type (e.g. linux-matrix-deploy) and the revision date in its first two lines.

• When inserting comments into custom code blocks, only one-line comments are allowed. Otherwise the update heuristic gets in trouble.

See Also

yaml_templates

Examples

## Not run: 
# auto-search
update_yml()

update_yml("tic.yml")

# custom named templates
update_yml("custom-name.yml")

# full paths
update_yml("~/path/to/repo/.github/workflows/tic.yml")

## End(Not run)

Description

Creates a public-private key pair, adds the public key to the GitHub repository via github_add_key(), and stores the private key as a "secret" in the GitHub repo.

Usage

use_ghactions_deploy(
  path = usethis::proj_get(),
  repo = get_repo_slug(remote),
  key_name_private = "TIC_DEPLOY_KEY",
  key_name_public = "Deploy key for GitHub Actions",
  remote = "origin"
)

Arguments

Description

Prepares a repo for building and deploying supported by tic.

Usage

use_tic(
  wizard = interactive(),
  linux = "ghactions",
  mac = "ghactions",
  windows = "ghactions",
  deploy = "ghactions",
  matrix = "none",
  private_key_name = "TIC_DEPLOY_KEY",
  quiet = FALSE
)

Arguments

Details

1. Query information which CI providers should be used

2. Setup permissions for providers selected for deployment

3. Create YAML files for selected providers

4. Create a default tic.R file depending on the repo type (package, website, bookdown, ...)

Examples

# Requires interactive mode
if (FALSE) {
  use_tic()

  # Pre-specified settings favoring Circle CI:
  use_tic(
    wizard = FALSE,
    linux = "circle",
    mac = "ghactions",
    windows = "ghactions",
    deploy = "circle",
    matrix = "all"
  )
}

Description

Adds a CI status badge to README.Rmd or README.md. By default the label is "tic".

A custom branch can be specified via argument branch.

Usage

use_tic_badge(provider, branch = NULL, label = "tic")

Arguments

Examples

## Not run: 
use_tic_badge(provider = "ghactions")

# use a different branch
use_tic_badge(provider = "ghactions", branch = "develop")

## End(Not run)

Description

Adds a tic.R file to containing the macros/steps/stages to be run during CI runs.

The content depends on the repo type (detected automatically when used within use_tic()).

Usage

use_tic_r(repo_type, deploy_on = "none")

Arguments

See Also

yaml_templates, use_tic_badge()

Examples

## Not run: 
use_tic_r("package")
use_tic_r("package", deploy_on = "ghactions")
use_tic_r("blogdown", deploy_on = "all")

## End(Not run)

Description

Adds a GitHub Actions workflow (update-tic.yml) to check for tic template updates once a day.

Internally, update_yml() is called. A Pull Request will be opened if a newer upstream version of the local tic template is found.

This workflow relies on a GITHUB_PAT with "workflow" scopes if GitHub Actions templates should be updated. Generate a GITHUB PAT and add it as a secret to your repo with gha_add_secret().

Usage

use_update_tic()

Examples

## Not run: 
use_update_tic()

## End(Not run)

Description

Installs YAML templates for various CI providers. These functions are also used within use_tic().

If you want to update an existing template use update_yml().

Usage

use_circle_yml(type = "linux-deploy", write = TRUE, quiet = FALSE)

use_ghactions_yml(type = "linux-deploy", write = TRUE, quiet = FALSE)

Arguments

pkgdown

If type contains "deploy", tic by default also sets the environment variable BUILD_PKGDOWN=true. This triggers a call to pkgdown::build_site() via the do_pkgdown macro in tic.R for the respective runners.

If a setting includes "matrix" and builds on multiple R versions, the job building on R release is chosen to build the pkgdown site.

YAML Type

tic supports a variety of different YAML templates which follow the ⁠<platform>-<action>⁠ pattern. The first one is mandatory, the others are optional.

• Possible values for ⁠<platform>⁠ are linux, and macos, windows.

• Possible values for ⁠<action>⁠ are matrix and deploy.

Special types are custom and custom-deploy. These should be used if the runner matrix is completely user-defined. This is mainly useful in update_yml().

For backward compatibility use_ghactions_yml() will be default build and deploy on all platforms.

Here is a list of all available combinations: