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] |
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 |
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.
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]
Useful links:
Report bugs at https://github.com/ropensci/circle/issues
## 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)
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.
browse_circle_token()
browse_circle_token()
Returns TRUE
(invisibly).
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>
## Not run: browse_circle_token() edit_circle_config() ## End(Not run)
## Not run: browse_circle_token() edit_circle_config() ## End(Not run)
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.
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)
repo |
|
user |
|
limit |
|
vcs_type |
|
api_version |
|
pipeline_id |
|
workflow_id |
|
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.
An object of class circle_collection
containing list
information on the queried Circle CI pipelines/workflows/jobs.
## 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)
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.
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 )
repo |
|
user |
|
type |
|
api_version |
|
vcs_type |
|
quiet |
|
fingerprint |
|
preferred |
|
An object of class circle_api
with the following elements
content
(queried content)
path
(API request)
response
(HTTP response information)
## 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)
Workhorse function for executing API requests to Circle CI.
circle( verb = "GET", path = "", query = list(), body = "", api_version = "v2", encode = "json" )
circle( verb = "GET", path = "", query = list(), body = "", api_version = "v2", encode = "json" )
verb |
|
path |
|
query |
|
body |
|
api_version |
|
encode |
|
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.
An object of class circle_api
with the following elements
content
(queried content)
path
(API request)
response
(HTTP response information)
## 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)
Opens ~/.circleci/cli.yml
.
edit_circle_config()
edit_circle_config()
No return value, called for side effects.
"Follows" a repo on Circle CI so that builds can be triggered.
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 )
repo |
|
user |
|
vcs_type |
|
api_version |
|
quiet |
|
An object of class circle_api
with the following elements
content
(queried content)
path
(API request)
response
(HTTP response information)
## Not run: enable_repo() ## End(Not run)
## Not run: enable_repo() ## End(Not run)
Add, get or set Circle CI environment variable(s) for a repo on Circle CI.
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 )
name |
|
repo |
|
user |
|
vcs_type |
|
api_version |
|
var |
|
quiet |
|
An object of class circle_api
with the following elements
content
(queried content)
path
(API request)
response
(HTTP response information)
## 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)
Retrieve artifacts from a specific build.
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" )
job_id |
|
repo |
|
user |
|
vcs_type |
|
api_version |
|
An object of class circle_api
with the following elements
content
(queried content)
path
(API request)
response
(HTTP response information)
## 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)
Retrieve details about the authenticated Circle CI user.
get_circle_user()
get_circle_user()
A named vector of class circle_user
containing information about
about the authenticated user:
Full name
Username
ID
API endpoint
## Not run: get_circle_user() ## End(Not run)
## Not run: get_circle_user() ## End(Not run)
Retrieve a list of Circle CI repositories for the authenticated user.
list_projects(repo = github_info()$name, user = github_info()$owner$login)
list_projects(repo = github_info()$name, user = github_info()$owner$login)
repo |
|
user |
|
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.
An object of class circle_api
with the following elements
content
(queried content)
path
(API request)
response
(HTTP response information)
get_pipelines()
, get_workflows()
, get_jobs()
## Not run: list_projects() ## End(Not run)
## Not run: list_projects() ## End(Not run)
Triggers a new build for a specific repo branch.
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 )
repo |
|
user |
|
vcs_type |
|
branch |
A character string specifying the repository branch. |
quiet |
|
Trigger a new Circle CI build for a specific repo branch.
An object of class circle_api
with the following elements
content
(queried content)
path
(API request)
response
(HTTP response information)
## Not run: new_build() ## End(Not run)
## Not run: new_build() ## End(Not run)
Creates a Circle CI "user-key" (= SSH key pair) if none exists yet to enable deployment from Circle CI builds to GitHub.
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 )
repo |
|
user |
|
quiet |
|
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.
No return value, called for side effects.
## Not run: use_circle_deploy() ## End(Not run)
## Not run: use_circle_deploy() ## End(Not run)