In cloudyr/circleci: Circle CI API Client Package

Circle CI API Client Package

circleci is a simple client package for the Circle CI REST API. It can control containerized builds of R packages and other software projects as part of a continuous integration workflow. Builds are controlled by the circle.yml file in your project repository, though build settings and environment variables can additionally be managed through this package. The package also provides functionality for monitoring past builds, as well as canceling and retrying builds.

The documentation for Travis-CI may be particularly useful for configuring a circle.yml file. Note that Circle has native R support, but does not run the latest R version. This means it may be a particularly useful platform R development, but packages will require the installation of R-devel (as is provided by the R Travis community support) or by running tests within a Docker container.

Installation

This package is not yet on CRAN. To install the latest development version from GitHub, run the following:

if(!require("devtools")){
    install.packages("devtools")
    library("devtools")
}
install_github("cloudyr/circleci")

Code Examples

To use the Circle CI API, you will need an account and an API key. Keys can be created on the Circle CI account dashboard. This value should then be set as an environment variable:

Sys.setenv("CIRCLE_CI_KEY" = "examplecirclekey123")

A simple "Hello World!" test of authentication is to retrieve one's own user data using:

str(get_user())

Listing projects and builds

It's then quite simple to list your projects or builds:

# list projects
p <- list_projects()
p

# list builds
b <- list_builds()
b

# list builds for a given project
list_builds(project = p[[1]])

You can also retrieve details of a given build:

# using a build object:
get_build(b[[1]])

# using a build number, project, and username:
get_build(b[[1]]$build_num, b[[1]]$reponame, b[[1]]$username)

Starting, restarting, and canceling builds

The most useful aspects of the package (and the API) relate to the ability to control builds:

# retry a build
new <- retry_build(b[[1]])

# cancel that build
cancel_build(new)

# trigger a new build for a project
p <- list_projects()
new_build(p[[1]])

Adding and deleting environment variables

Another useful feature of the package is the ability to add and remove environment variables from the build environment. These environment variables control the build environment and can be used within a build, for example for unit testing.

p <- list_projects()

# add environment variable
add_env(project = p[[1]], var = list(Variable1 = "abc", Variable2 = "def"))

# delete an environment variable (one per call)
delete_env(project = p[[1]], var = "Variable1")
delete_env(project = p[[1]], var = "Variable2")