Package 'circle' reference manual

Title:	R Client Package for Circle CI
Description:	Tools for interacting with the 'Circle CI' API (<https://circleci.com/docs/api/v2/>). Besides executing common tasks such as querying build logs and restarting builds, this package also helps setting up permissions to deploy from builds.
Authors:	Patrick Schratz [aut, cre] , Max Joseph [rev] (Max reviewed the package for ropensci, see <https://github.com/ropensci/software-review/issues/356>), Sharla Gelfand [rev] (Sharla reviewed the package for ropensci, see <https://github.com/ropensci/software-review/issues/356>)
Maintainer:	Patrick Schratz <[email protected]>
License:	GPL-3
Version:	0.7.3
Built:	2024-08-29 23:09:12 UTC
Source:	https://github.com/ropensci/circle

Circle CI API Client

Description

This package provides functionality for interacting with the Circle CI API. Circle CI is a continuous integration provider which allows for automated testing of software each time that software is publicly committed to a repository on GitHub.

This package interacts with the Circle CI REST API and allows to execute tasks in R without visiting the the website. This includes monitoring builds, modifying build environment settings and environment variables, and cancelling or restarting builds.

Use of this package requires a Circle API key. Unless a key is already set, users will be guided through the creation of a key, API keys are disposable, but should still be treated securely.

The following functions simplify integrating R package testing and deployment with GitHub and Circle CI:

enable_repo() enables Circle CI for your repository,
use_circle_deploy() installs a public deploy key on GitHub and the corresponding private key on Circle CI to simplify deployments to GitHub from Circle CI.

Author(s)

Maintainer: Patrick Schratz [email protected] (ORCID)

Other contributors:

Max Joseph (Max reviewed the package for ropensci, see <https://github.com/ropensci/software-review/issues/356>) [reviewer]
Sharla Gelfand (Sharla reviewed the package for ropensci, see <https://github.com/ropensci/software-review/issues/356>) [reviewer]

Examples

## Not run: 
# check to see if you've authenticated correctly
get_circle_user()

## End(Not run)

## Not run: 
# check to see if you've authenticated correctly
get_circle_user()

## End(Not run)

Authenticate to Circle CI

Description

A Circle CI API token is needed to interact with the Circle CI API. browse_circle_token() opens a browser window for the respective Circle CI endpoint to retrieve the key.

Usage

browse_circle_token()
browse_circle_token()

Value

Returns TRUE (invisibly).

Store API token

circle supports two ways of storing the Circle API tokens:

via env vars R_CIRCLE
via ⁠~/.circleci/cli.yml⁠

The latter should already be present if you already used the circle CLI tool at some point in the past. If not, its up to your preference which approach to use.

The following instructions should help to set up ⁠~/.circleci/cli.yml⁠ correctly:

Copy the token from the browser after having called browse_circle_token(). You can use edit_circle_config() to open ⁠~/.circleci/cli.yml⁠.

The token should be stored using the following structure

host: https://circleci.com
endpoint: graphql-unstable
token: <token>

Examples

## Not run: 
browse_circle_token()

edit_circle_config()

## End(Not run)
## Not run: 
browse_circle_token()

edit_circle_config()

## End(Not run)

Retrieve Metadata from Circle CI Builds

Description

Query information about pipelines, workflows or jobs on Circle CI. The S3 print() method for these functions returns the respective pipeline IDs. To inspect the details of each pipeline, save the return value in an object and inspect the respective sub-lists.

If no pipeline or workflow is supplied to get_workflows()/get_jobs(), the ten most recent pipelines/jobs are queried, respectively.

Usage

get_pipelines(
  repo = github_info()$name,
  user = github_info()$owner$login,
  limit = 30,
  vcs_type = "gh",
  api_version = "v2"
)

get_workflows(
  pipeline_id = NULL,
  repo = github_info()$name,
  user = github_info()$owner$login
)

get_jobs(
  workflow_id = NULL,
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh"
)

retry_workflow(workflow_id = NULL)
get_pipelines(
  repo = github_info()$name,
  user = github_info()$owner$login,
  limit = 30,
  vcs_type = "gh",
  api_version = "v2"
)

get_workflows(
  pipeline_id = NULL,
  repo = github_info()$name,
  user = github_info()$owner$login
)

get_jobs(
  workflow_id = NULL,
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh"
)

retry_workflow(workflow_id = NULL)

Arguments

`repo`	`⁠[character]⁠` The repository slug to use. Must follow the "`user/repo`" structure.
`user`	`⁠[character]⁠` The username for the repository. By default queried using `get_user()`.
`limit`	`⁠[integer]⁠` How many builds should be returned? Maximum allowed by Circle is 30.
`vcs_type`	`⁠[character]⁠` The version control system to use. Defaults to "gh" (Github).
`api_version`	`⁠[character]⁠` A character string specifying the Circle CI API version. This usually does not need to be changed by the user.
`pipeline_id`	`⁠[character]⁠` A Circle CI pipeline ID.
`workflow_id`	`⁠[character]⁠` A Circle CI workflow ID.

Details

While the ⁠get_*()⁠ functions query information about the respective build level details (pipeline - workflow - job), retry_workflow() let's users rerun a specific workflow. By default, the workflow from the most recent pipeline will be rerun if no pipeline ID was supplied.

Value

An object of class circle_collection containing list information on the queried Circle CI pipelines/workflows/jobs.

Examples

## Not run: 
pipelines <- get_pipelines()

workflows <- get_workflows()

jobs <- get_jobs()

# rerun most recent workflow
retry_workflow()

## End(Not run)
## Not run: 
pipelines <- get_pipelines()

workflows <- get_workflows()

jobs <- get_jobs()

# rerun most recent workflow
retry_workflow()

## End(Not run)

Interact with "Checkout Keys" on Circle CI

Description

Create, delete, query or check different types of checkout keys for a specific Circle CI project. Valid values for argument type are "user-key" or "deploy-key".

A "Checkout Key" on Circle CI is a specific SSH key which is used to checkout repositories into a Circle CI build and possible deploy changes to the repository. Circle CI subdivides "Checkout Keys" into "user-key" and "deploy-key".

Please see "Deployment" section in the "Getting Started" vignette for more information.

Usage

create_checkout_key(
  repo = github_info()$name,
  user = github_info()$owner$login,
  type = "user-key",
  api_version = "v2",
  vcs_type = "gh",
  quiet = FALSE
)

get_checkout_keys(
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v2"
)

delete_checkout_key(
  fingerprint = NULL,
  repo = github_info()$name,
  user = github_info()$owner$login,
  type = "user-key",
  api_version = "v2",
  vcs_type = "gh"
)

has_checkout_key(
  repo = github_info()$name,
  user = github_info()$owner$login,
  type = "github-user-key",
  vcs_type = "gh",
  preferred = TRUE
)
create_checkout_key(
  repo = github_info()$name,
  user = github_info()$owner$login,
  type = "user-key",
  api_version = "v2",
  vcs_type = "gh",
  quiet = FALSE
)

get_checkout_keys(
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v2"
)

delete_checkout_key(
  fingerprint = NULL,
  repo = github_info()$name,
  user = github_info()$owner$login,
  type = "user-key",
  api_version = "v2",
  vcs_type = "gh"
)

has_checkout_key(
  repo = github_info()$name,
  user = github_info()$owner$login,
  type = "github-user-key",
  vcs_type = "gh",
  preferred = TRUE
)

Arguments

`repo`	`⁠[character]⁠` The repository slug to use. Must follow the "`user/repo`" structure.
`user`	`⁠[character]⁠` The username for the repository. By default queried using `get_user()`.
`type`	`⁠[character]⁠` Type of key to add. Options are "user-key" and "deploy-key".
`api_version`	`⁠[character]⁠` A character string specifying the Circle CI API version. This usually does not need to be changed by the user.
`vcs_type`	`⁠[character]⁠` The version control system to use. Defaults to "gh" (Github).
`quiet`	`⁠[logical]⁠` If `TRUE`, console output is suppressed.
`fingerprint`	`⁠[character]⁠` The fingerprint of the checkout key which should be deleted.
`preferred`	`⁠[logical]⁠` Checks whether the requested type is the "preferred" key.

Value

An object of class circle_api with the following elements

content (queried content)
path (API request)
response (HTTP response information)

Examples

## Not run: 
# by default a "user-key" will be created which can also be used for build
# deployments
create_checkout_key()

# A "deploy-key" can only be used to checkout code from the repository into
# a Circle CI build
create_checkout_key(type = "deploy-key")

## End(Not run)
## Not run: 
get_checkout_keys()

## End(Not run)
## Not run: 
delete_checkout_key()

## End(Not run)
## Not run: 
has_checkout_key()

## End(Not run)
## Not run: 
# by default a "user-key" will be created which can also be used for build
# deployments
create_checkout_key()

# A "deploy-key" can only be used to checkout code from the repository into
# a Circle CI build
create_checkout_key(type = "deploy-key")

## End(Not run)
## Not run: 
get_checkout_keys()

## End(Not run)
## Not run: 
delete_checkout_key()

## End(Not run)
## Not run: 
has_checkout_key()

## End(Not run)

Circle CI HTTP Requests

Description

Workhorse function for executing API requests to Circle CI.

Usage

circle(
  verb = "GET",
  path = "",
  query = list(),
  body = "",
  api_version = "v2",
  encode = "json"
)
circle(
  verb = "GET",
  path = "",
  query = list(),
  body = "",
  api_version = "v2",
  encode = "json"
)

Arguments

`verb`	`⁠[character]⁠` A character string containing an HTTP verb, defaulting to `GET`.
`path`	`⁠[character]⁠` A character string with the API endpoint (should begin with a slash).
`query`	`⁠[character]⁠` A list specifying any query string arguments to pass to the API. This is used to pass the API token.
`body`	`⁠[character]⁠` A named list or array of what should be passed in the request. Corresponds to the "-d" argument of the `curl` command.
`api_version`	`⁠[character]⁠` A character string specifying the Circle CI API version. This usually does not need to be changed by the user.
`encode`	`⁠[character]⁠` Encoding format. See httr::POST.

Details

In almost all cases, users should not need to execute API calls directly. However, if desired this functions makes it possible to issue any API request. If you experience calling a custom request heavily, consider opening a feature request on GitHub.

Value

An object of class circle_api with the following elements

content (queried content)
path (API request)
response (HTTP response information)

Examples

## Not run: 
circle(verb = "GET", path = "/project/gh/ropensci/circle/checkout-key")

## End(Not run)
## Not run: 
circle(verb = "GET", path = "/project/gh/ropensci/circle/checkout-key")

## End(Not run)

Open circle Configuration file

Description

Opens ⁠~/.circleci/cli.yml⁠.

Usage

edit_circle_config()
edit_circle_config()

Value

No return value, called for side effects.

Enable a repo on Circle CI

Description

"Follows" a repo on Circle CI so that builds can be triggered.

Usage

enable_repo(
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v1.1",
  quiet = FALSE
)
enable_repo(
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v1.1",
  quiet = FALSE
)

Arguments

`repo`	`⁠[character]⁠` The repository slug to use. Must follow the "`user/repo`" structure.
`user`	`⁠[character]⁠` The username for the repository. By default queried using `get_user()`.
`vcs_type`	`⁠[character]⁠` The version control system to use. Defaults to "gh" (Github).
`api_version`	`⁠[character]⁠` A character string specifying the Circle CI API version. This usually does not need to be changed by the user.
`quiet`	`⁠[logical]⁠` If `TRUE`, console output is suppressed.

Value

An object of class circle_api with the following elements

content (queried content)
path (API request)
response (HTTP response information)

Examples

## Not run: 
enable_repo()

## End(Not run)
## Not run: 
enable_repo()

## End(Not run)

Interact with Environment Variable(s) on Circle CI

Description

Add, get or set Circle CI environment variable(s) for a repo on Circle CI.

Usage

get_env_vars(
  name = NULL,
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v2"
)

set_env_var(
  var,
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v2",
  quiet = FALSE
)

delete_env_var(
  var,
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v2",
  quiet = FALSE
)
get_env_vars(
  name = NULL,
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v2"
)

set_env_var(
  var,
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v2",
  quiet = FALSE
)

delete_env_var(
  var,
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v2",
  quiet = FALSE
)

Arguments

`name`	`⁠[character]⁠` Name of a specific environment variable. If not set, all env vars are returned.
`repo`	`⁠[character]⁠` The repository slug to use. Must follow the "`user/repo`" structure.
`user`	`⁠[character]⁠` The username for the repository. By default queried using `get_user()`.
`vcs_type`	`⁠[character]⁠` The version control system to use. Defaults to "gh" (Github).
`api_version`	`⁠[character]⁠` A character string specifying the Circle CI API version. This usually does not need to be changed by the user.
`var`	`⁠[list]⁠` A list containing key-value pairs of environment variable and its value.
`quiet`	`⁠[logical]⁠` If `TRUE`, console output is suppressed.

Value

An object of class circle_api with the following elements

content (queried content)
path (API request)
response (HTTP response information)

Examples

## Not run: 
# get env var
get_env_vars()

# set env var
set_env_var(var = list("foo" = "123"))

# delete env var
delete_env_var("foo")

## End(Not run)
## Not run: 
# get env var
get_env_vars()

# set env var
set_env_var(var = list("foo" = "123"))

# delete env var
delete_env_var("foo")

## End(Not run)

Get Build Artifacts of a Specific Job

Description

Retrieve artifacts from a specific build.

Usage

get_build_artifacts(
  job_id = NULL,
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v2"
)
get_build_artifacts(
  job_id = NULL,
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  api_version = "v2"
)

Arguments

`job_id`	`⁠[character]⁠` A Circle CI job id.
`repo`	`⁠[character]⁠` The repository slug to use. Must follow the "`user/repo`" structure.
`user`	`⁠[character]⁠` The username for the repository. By default queried using `get_user()`.
`vcs_type`	`⁠[character]⁠` The version control system to use. Defaults to "gh" (Github).
`api_version`	`⁠[character]⁠` A character string specifying the Circle CI API version. This usually does not need to be changed by the user.

Value

An object of class circle_api with the following elements

content (queried content)
path (API request)
response (HTTP response information)

Examples

## Not run: 
job_id <- get_jobs()[[1]]$id
get_build_artifacts(job_id)

## End(Not run)
## Not run: 
job_id <- get_jobs()[[1]]$id
get_build_artifacts(job_id)

## End(Not run)

Get Circle CI user

Description

Retrieve details about the authenticated Circle CI user.

Usage

get_circle_user()
get_circle_user()

Value

A named vector of class circle_user containing information about about the authenticated user:

Full name
Username
ID
API endpoint

Examples

## Not run: 
get_circle_user()

## End(Not run)
## Not run: 
get_circle_user()

## End(Not run)

List Circle CI Projects

Description

Retrieve a list of Circle CI repositories for the authenticated user.

Usage

list_projects(repo = github_info()$name, user = github_info()$owner$login)
list_projects(repo = github_info()$name, user = github_info()$owner$login)

Arguments

`repo`	`⁠[character]⁠` The repository slug to use. Must follow the "`user/repo`" structure.
`user`	`⁠[character]⁠` The username for the repository. By default queried using `get_user()`.

Details

Retrieves a very detailed list of repository and repo-related information for all Circle CI repository attached to the current user.

This endpoint uses API v1.1 and will probably be removed in the near future.

Value

An object of class circle_api with the following elements

content (queried content)
path (API request)
response (HTTP response information)

Examples

## Not run: 
list_projects()

## End(Not run)
## Not run: 
list_projects()

## End(Not run)

Trigger a New Build on Circle CI

Description

Triggers a new build for a specific repo branch.

Usage

new_build(
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  branch = "master",
  quiet = FALSE
)
new_build(
  repo = github_info()$name,
  user = github_info()$owner$login,
  vcs_type = "gh",
  branch = "master",
  quiet = FALSE
)

Arguments

`repo`	`⁠[character]⁠` The repository slug to use. Must follow the "`user/repo`" structure.
`user`	`⁠[character]⁠` The username for the repository. By default queried using `get_user()`.
`vcs_type`	`⁠[character]⁠` The version control system to use. Defaults to "gh" (Github).
`branch`	A character string specifying the repository branch.
`quiet`	`⁠[logical]⁠` If `TRUE`, console output is suppressed.

Details

Trigger a new Circle CI build for a specific repo branch.

Value

An object of class circle_api with the following elements

content (queried content)
path (API request)
response (HTTP response information)

Examples

## Not run: 
new_build()

## End(Not run)
## Not run: 
new_build()

## End(Not run)

Set Up Build Deployment Between Circle CI And Github

Description

Creates a Circle CI "user-key" (= SSH key pair) if none exists yet to enable deployment from Circle CI builds to GitHub.

Usage

use_circle_deploy(
  repo = github_info()$name,
  user = github_info()$owner$login,
  quiet = FALSE
)
use_circle_deploy(
  repo = github_info()$name,
  user = github_info()$owner$login,
  quiet = FALSE
)

Arguments

`repo`	`⁠[character]⁠` The repository slug to use. Must follow the "`user/repo`" structure.
`user`	`⁠[character]⁠` The username for the repository. By default queried using `get_user()`.
`quiet`	`⁠[logical]⁠` If `TRUE`, console output is suppressed.

Details

The easiest way to achieve a deployment from Circle CI builds to a Github repo is by creating a so called "user-key" (i.e. an SSH key pair) on Circle CI.

use_circle_deploy() tries to be smart by exiting early if such a key is already present.

If the repo has not been enabled yet on Circle CI, please run enable_repo() first. Also to be able to authenticate to Github in the first place a personal access token needs to be set (via env var GITHUB_TOKEN). usethis::github_token() can be used to check if one is already set. If none is set, this function will prompt you to create one.

Value

No return value, called for side effects.

Examples

## Not run: 
use_circle_deploy()

## End(Not run)
## Not run: 
use_circle_deploy()

## End(Not run)

Package 'circle'

Help Index

Circle CI API Client

Description

Author(s)

See Also

Examples

Authenticate to Circle CI

Description

Usage

Value

Store API token

Examples

Retrieve Metadata from Circle CI Builds

Description

Usage

Arguments

Details

Value

Examples

Interact with "Checkout Keys" on Circle CI

Description

Usage

Arguments

Value

Examples

Circle CI HTTP Requests

Description

Usage

Arguments

Details

Value

Examples

Open circle Configuration file

Description

Usage

Value

Enable a repo on Circle CI

Description

Usage

Arguments

Value

Examples

Interact with Environment Variable(s) on Circle CI

Description

Usage

Arguments

Value

Examples

Get Build Artifacts of a Specific Job

Description

Usage

Arguments

Value

Examples

Get Circle CI user

Description

Usage

Value

Examples

List Circle CI Projects

Description

Usage

Arguments

Details

Value

See Also

Examples

Trigger a New Build on Circle CI

Description

Usage

Arguments

Details

Value

See Also

Examples

Set Up Build Deployment Between Circle CI And Github

Description

Usage

Arguments