circle

R client package for the Continuous Integration (CI) provider 'Circle CI'. Circle CI stands in line with GitHub Actions, Travis CI, AppVeyor and many more CI providers. Circle CI heavily relies on Docker containers for runner execution.

Continuous Integration (CI) / Continuous Deployment (CD) is heavily used in the IT world to automatically perform certain actions after a specific trigger (e.g. after each commit). When developing R packages the most common uses cases are to check the package on each commit for CRAN eligibility (by running R CMD Check) and to deploy a {pkgdown} documentation page for the package.

This package aims help to set up CI/CD with the service provider Circle CI and provides R functions to execute CI specific tasks such as build restarts, log queries or setting environment variables from within R. It also simplifies the setup process for build deployments via use_circle_deploy(). All functionality relies on calls to the Circle CI REST API.

There are two ways to use this package:

• Via the high-level functions of this package which wrap common API calls:
  • get_pipelines()
  • get_checkout_keys()
  • set_env_var()
  • etc.
• Via direct API calls through the workhorse function circle().

{circle} does not come with an option to setup Circle CI YAML files. Please see the related {tic} package for such functionality and more CI workflow related tools. {circle} aims to provide a handy and flexible high-level interface to the Circle CI API without shipping opinionated workflow functionality.

API versions

All functionality uses the Circle CI API v2 which follows the pipelines -> workflows -> jobs approach. This API version is still in beta and might undergo some changes in the near future.

Some functions/endpoints can also be used via API versions v1.1 and v1 by setting the api_version argument. However, this will only work if the respective API endpoint is available for the chosen API version. Usually, there should be no need in practice to fall back to API version < 2.

For more information on the differences between the Circle CI API versions, have a look at the document explaining changes between v1.1 and v2.

Installation

Development Version:

remotes::install_github("ropensci/circle")

Get Started

See the Getting Started vignette for an introduction.

Note to Developers

This packages relies on private API keys for local testing. See CONTRIBUTING.md#testing-the-package for detailed instructions.

Acknowledgments

This package was inspired by the work of Thomas J. Leeper on the (discontinued) cloudyr/circleci package and by the (archived) ropenscilabs/travis package.