circleci

Circle CI API Wrapper. Requires ruby >= 2.0.0.

⚠️ 403 Forbidden issue with GET Requests fixed in 2.1.0

Install

gem install circleci

or with Bundler

gem 'circleci'

Usage

Documentation

Documentation can be found on rubydoc or in this README

Configuring

Global Config

Configure using an API token from Circle

CircleCi.configure do |config|
  config.token = 'my-token'
end

Optionally you can configure your own host and/or port if using an enterprise CircleCi host. The port will default to 80 if not set.

CircleCi.configure do |config|
  config.token = 'my-token'
  config.host = 'https://ci.mycompany.com'
  config.port = 1234
end

Overriding request settings such as not verifying SSL

CircleCi.configure do |config|
  config.token = ENV['CIRCLECI_TOKEN']
  config.host = 'http://ci.mycompany.com'
  config.port = 80
  config.request_overrides = {
    use_ssl: false,
    verify_ssl: false
  }
end

Setup for proxying requests

require 'circleci'

CircleCi.configure do |config|
  config.token = ENV['CIRCLECI_TOKEN']
  config.proxy_host = 'http://ciproxy.mycompany.com'
  config.proxy_port = 8000
  config.proxy_user = 'myci'
  config.proxy_pass = 'supersecret'
  config.proxy = true
end

Config Object

If you need to use custom config per request or for specific non-global cases you can instantiate a CircleCi::Config object with all the same granularity as a global config.

# Using a new token
config = CircleCi::Config.new token: ENV['SECRET_CIRCLECI_TOKEN']

# Setting a new host
config_options = { host: ENV['CIRCLECI_HOST'], port: ENV['CIRCLECI_PORT'] }
config = CircleCi::Config.new

# Proxy setup is a little more invovled right now
# and requires setting proxy info on instantiated config
config = CircleCi::Config.new token: ENV['CIRCLECI_TOKEN'], proxy: true
config.proxy_host = ENV['CIRCLECI_PROXY_HOST']
config.proxy_port = ENV['CIRCLECI_PROXY_PORT']
config.proxy_user = ENV['CIRCLECI_PROXY_USER']
config.proxy_pass = ENV['CIRCLECI_PROXY_PASS']

API Versioning

CircleCi is a versioned API. This gem attempts to stay up to date with any changes between versions. As of now you can change the version on the config you use to make requests.

config = CircleCi::Config.new token: ENV['CIRCLECI_TOKEN'], version: 'v1.1'

This will change the requests to be in the format of

https://circleci.com/api/v1.1/

VCS Type

Introduced in v1.1 of the API is interacting with projects and builds based on their version control system type. Currently this can be github or bitbucket. Please see endpoint documentation for Project and Build on usage but you can set a vcs type on either as so

# A bitbucket project
project = CircleCi::Project.new 'username', 'project', 'bitbucket'

# A github build
build = CircleCi::Build.new 'username', 'project', 'github', '1234'

# Defaults to github
build = CircleCi::Build.new 'username', 'project', nil, '1234'
build.vcs_type # will be github

# Non-valid types default to github as well
project = CircleCi::Project.new 'username', 'project', 'gitlab'
project.vcs_type # will be github

API Endpoints

User
- Heroku Key
- Me
Project
- All
- Build Branch
- Build SSH Key
- Clear Cache
- Enable
- Envvar
- Follow
- Delete Checkout Key
- Get Checkout Key
- List Checkout Keys
- New Checkout Key
- Recent Project Builds
- Recent Builds Branch
- Settings
- Add Envvar
- Delete Envvar
- SSH Key
- Unfollow
Build
- Artifacts
- Cancel
- Get
- Retry
- Tests
Recent Builds
- Get Recent Builds

User

heroku_key

Endpoint: /user/heroku-key

Adds your Heroku API key to CircleCI.

# Use global config with token for user
user = CircleCi::User.new
user.heroku_key 'your-api-key'

# Use a different config with another user token
user = CircleCi::User.new other_user_config
user.heroku_key 'your-api-key'

Example response

Empty body response with a 200 OK response code

""

me

Endpoint: /me

Provides information about the signed in user.

# Use global config with token for user
user = CircleCi::User.new
user.me

# Use a different config with another user token
user = CircleCi::User.new other_user_config
user.me

Example response

{
  "basic_email_prefs" : "smart", // can be "smart", "none" or "all"
  "login" : "pbiggar" // your github username
}

Project

all

Endpoint: /projects

List of all the repos you have access to on Github, with build information organized by branch.

# Use global config with token for user
projects = CircleCi::Projects.new
projects.get

# Use a different config with another projects token
projects = CircleCi::Projects.new other_projects_config
projects.get

Example response

[ {
  "vcs_url": "https://github.com/circleci/mongofinil"
  "followed": true // true if you follow this project in Circle
  "branches" : {
    "master" : {
      "pusher_logins" : [ "pbiggar", "arohner" ], // users who have pushed
      "last_non_success" : { // last failed build on this branch
        "pushed_at" : "2013-02-12T21:33:14Z",
        "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
        "build_num" : 22,
        "outcome" : "failed",
        },
      "last_success" : { // last successful build on this branch
        "pushed_at" : "2012-08-09T03:59:53Z",
        "vcs_revision" : "384211bbe72b2a22997116a78788117b3922d570",
        "build_num" : 15,
        "outcome" : "success",
        },
      "recent_builds" : [ { // last 5 builds, ordered by pushed_at (decreasing)
        "pushed_at" : "2013-02-12T21:33:14Z",
        "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
        "build_num" : 22,
        "outcome" : "failed",
        }, {
        "pushed_at" : "2013-02-11T03:09:54Z",
        "vcs_revision" : "0553ba86b35a97e22ead78b0d568f6a7c79b838d",
        "build_num" : 21,
        "outcome" : "failed",
        }, ... ],
      "running_builds" : [ ] // currently running builds
    }
  }
} ]

build_branch

Endpoint: /project/:username/:repository/tree/:branch

Build a specific branch of a project

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'

# Build the latest push for this branch
latest_build = project.build_branch 'branch'

# Adding URL params for revision or parallel
params = { revision: 'fda12345asdf', parallel: 2 }
res = project.build_branch 'branch', params
res.body['status'] # Not running
res.body['build_url'] # Get url of build

# Passing build parameters in the post body
build_params = { build_parameters: { 'MY_TOKEN' => '123asd123asd' } }
res = project.build_branch 'branch', {}, build_params
res.body['status']
res.body['build_url']

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.build_branch 'branch'

Example response

{
  "compare" : null,
  "previous_successful_build" : {
    "build_time_millis" : 40479,
    "status" : "success",
    "build_num" : 76
  },
  "build_parameters" : { },
  "committer_date" : "2014-07-27T14:40:15Z",
  "body" : "",
  "usage_queued_at" : "2014-07-29T14:05:36.373Z",
  "retry_of" : null,
  "reponame" : "soapy_cake",
  "build_url" : "https://circleci.com/gh/ad2games/soapy_cake/77",
  "parallel" : 1,
  "failed" : null,
  "branch" : "master",
  "username" : "ad2games",
  "author_date" : "2014-07-27T14:40:15Z",
  "why" : "edit",
  "user" : {
    "is_user" : true,
    "login" : "hwartig",
    "name" : "Harald Wartig",
    "email" : "hw@ad2games.com"
  },
  "vcs_revision" : "f932ea1b564ceaaa8cdba06b1bb93e1869a9a905",
  "build_num" : 77,
  "infrastructure_fail" : false,
  "ssh_enabled" : null,
  "committer_email" : "hwartig@gmail.com",
  "previous" : {
    "build_time_millis" : 40479,
    "status" : "success",
    "build_num" : 76
  },
  "status" : "not_running",
  "committer_name" : "Harald Wartig",
  "retries" : null,
  "subject" : "Fix link to api_versions.yml",
  "timedout" : false,
  "dont_build" : null,
  "feature_flags" : { },
  "lifecycle" : "not_running",
  "stop_time" : null,
  "build_time_millis" : null,
  "circle_yml" : null,
  "messages" : [ ],
  "is_first_green_build" : false,
  "job_name" : null,
  "start_time" : null,
  "all_commit_details" : [ {
    "committer_date" : "2014-07-27T14:40:15Z",
    "body" : "",
    "author_date" : "2014-07-27T14:40:15Z",
    "committer_email" : "hwartig@gmail.com",
    "commit" : "f932ea1b564ceaaa8cdba06b1bb93e1869a9a905",
    "committer_login" : "hwartig",
    "committer_name" : "Harald Wartig",
    "subject" : "Fix link to api_versions.yml",
    "commit_url" : "https://github.com/ad2games/soapy_cake/commit/f932ea1b564ceaaa8cdba06b1bb93e1869a9a905",
    "author_login" : "hwartig",
    "author_name" : "Harald Wartig",
    "author_email" : "hwartig@gmail.com"
  } ],
  "outcome" : null,
  "vcs_url" : "https://github.com/ad2games/soapy_cake",
  "author_name" : "Harald Wartig",
  "node" : null,
  "canceled" : false,
  "author_email" : "hwartig@gmail.com"
}

It also supports the Experimental Parameterized Builds

  build_environment_variables = {"ENV_VAR1" => "VALUE1", "ENV_VAR2" => "VALUE2"}
  res = CircleCi::Project.build_branch 'username', 'reponame', 'branch', build_environment_variables

build_ssh_key

Endpoint: /project/:username/:repository/:build_num/ssh-users

Adds a user to the build's SSH permissions.

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.build_ssh_key 'username', 'repo', 'RSA private key', 'hostname'

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.build_ssh_key 'username', 'repo', 'RSA private key', 'hostname'

Example response

Empty response body with a 200 OK successful response code

""

clear_cache

Endpoint: /project/:username/:repository/build-cache

Clears the cache for a project

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.clear_cache

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.clear_cache

Example response

{
  "status" : "build caches deleted"
}

delete_checkout_key

Endpoint: /project/:username/:repository/checkout-key/:fingerprint

Delete a checkout key for a project by supplying the fingerprint of the key.

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.delete_checkout_key 'fingerprint'

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.delete_checkout_key 'fingerprint'

Example response

{"message":"ok"}

enable

Endpoint: /project/:username/:repository/enable

Enable a project in CircleCI. Causes a CircleCI SSH key to be added to the GitHub. Requires admin privilege to the repository.

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.enable

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.enable

Example response

{
    "hall_notify_prefs": nil,
    "irc_password": nil,
    "default_branch": "master",
    "hipchat_notify": nil,
    "campfire_notify_prefs": nil,
    "campfire_room": nil,
    "irc_keyword": nil,
    "slack_api_token": nil,
    "parallel": 1,
    "github_user": nil,
    "github_permissions": {
        "admin": true,
        "push": true,
        "pull": true
    },
    "irc_server": nil,
    "heroku_deploy_user": nil,
    "dependencies": "",
    "slack_notify_prefs": nil,
    "ssh_keys": [

    ],
    "extra": "",
    "followed": false,
    "branches": {
        "master": {
            "last_non_success": {
                "added_at": "2014-06-05T17:23:25.352Z",
                "pushed_at": "2014-06-05T17:22:52.518Z",
                "vcs_revision": "66d398cb635c5f4dd666dd1526bda5894d1246e4",
                "build_num": 6,
                "status": "no_tests",
                "outcome": "no_tests"
            },
            "recent_builds": [
                {
                    "added_at": "2014-06-05T17:23:25.352Z",
                    "pushed_at": "2014-06-05T17:22:52.518Z",
                    "vcs_revision": "66d398cb635c5f4dd666dd1526bda5894d1246e4",
                    "build_num": 6,
                    "status": "no_tests",
                    "outcome": "no_tests"
                }
            ],
            "running_builds": [

            ]
        }
    },
    "campfire_token": nil,
    "hipchat_notify_prefs": nil,
    "test": "",
    "compile": "",
    "hipchat_room": nil,
    "slack_channel": nil,
    "slack_subdomain": nil,
    "vcs_url": "https://github.com/Shopify/google_auth",
    "flowdock_api_token": nil,
    "hall_room_api_token": nil,
    "slack_webhook_url": nil,
    "irc_username": nil,
    "hipchat_api_token": nil,
    "campfire_subdomain": nil,
    "has_usable_key": true,
    "setup": "",
    "irc_channel": nil,
    "feature_flags": {
        "build_GH1157_container_oriented_ui": nil,
        "set-github-status": true
    },
    "irc_notify_prefs": nil
}

envvar

Endpoint: /project/:username/:project/envvar

Get a list of environment variables for a project

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.envvar

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.envvar

Example response

[{"name":"foo","value":"xxxx"}]

follow

Endpoint: /project/:username/:repository/follow

Follow a project

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.follow

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.follow

Example response

{
    "followed": true,
    "first_build": nil
}

get_checkout_key

Endpoint: /project/:username/:repository/checkout-key/:fingerprint

Get a checkout key for a project by supplying the fingerprint of the key.

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.get_checkout_key 'fingerprint'

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.get_checkout_key 'fingerprint

Example response

{
    "public_key": "ssh-rsa...",
    "type": "deploy-key", // can be "deploy-key" or "user-key"
    "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
    "preferred": true,
    "time" : "2015-09-21T17:29:21.042Z" // when the key was issued
}

list_checkout_keys

Endpoint: /project/#{username}/#{project}/checkout-key

List checkout keys

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.checkout_keys

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.checkout_keys

Example response

[
    {
        "public_key": "ssh-rsa...",
        "type": "deploy-key", // can be "deploy-key" or "user-key"
        "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
        "preferred": true,
        "time" : "2015-09-21T17:29:21.042Z" // when the key was issued
    }
]

new_checkout_key

Endpoint: /project/:username/:repository/checkout-key

Create an ssh key used to access external systems that require SSH key-based authentication. Takes a type of key to create which an be deploy-key or github-user-key.

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.new_checkout_key 'deploy-key'

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.new_checkout_key 'deploy-key

Example response

{
    "public_key": "ssh-rsa...",
    "type": "deploy-key", // can be "deploy-key" or "user-key"
    "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
    "preferred": true,
    "time" : "2015-09-21T17:29:21.042Z" // when the key was issued
}

recent_project_builds

Endpoint: /project/:username/:repository

Build summary for each of the last 30 recent builds, ordered by build_num.

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.recent_builds

# Use params to filter by status
res = project.recent_builds filter: 'failed'

# Use params to limit and give an offset
res = project.recent_builds limit: 10, offset: 50

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.recent_builds

Example response

[ {
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/22",
  "build_num" : 22,
  "branch" : "master",
  "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
  "committer_name" : "Allen Rohner",
  "committer_email" : "arohner@gmail.com",
  "subject" : "Don't explode when the system clock shifts backwards",
  "body" : "", // commit message body
  "why" : "github", // short string explaining the reason we built
  "dont_build" : null, // reason why we didn't build, if we didn't build
  "queued_at" : "2013-02-12T21:33:30Z" // time build was queued
  "start_time" : "2013-02-12T21:33:38Z", // time build started running
  "stop_time" : "2013-02-12T21:34:01Z", // time build finished running
  "build_time_millis" : 23505,
  "lifecycle" : "finished",
  "outcome" : "failed",
  "status" : "failed",
  "retry_of" : null, // build_num of the build this is a retry of
  "previous" : { // previous build
    "status" : "failed",
    "build_num" : 21
  } ]

recent_builds_branch

Endpoint: /project/:username/:repository/tree/:branch

Build summary for each of the last 30 recent builds for a specific branch, ordered by build_num.

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.recent_builds_branch 'branch'

# Use params to filter by status
res = project.recent_builds_branch 'branch', filter: 'failed'

# Use params to limit and give an offset
res = project.recent_builds_branch 'branch', limit: 10, offset: 50

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.recent_builds_branch 'branch'

Example response

[ {
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/22",
  "build_num" : 22,
  "branch" : "new_feature",
  "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
  "committer_name" : "Allen Rohner",
  "committer_email" : "arohner@gmail.com",
  "subject" : "Don't explode when the system clock shifts backwards",
  "body" : "", // commit message body
  "why" : "github", // short string explaining the reason we built
  "dont_build" : null, // reason why we didn't build, if we didn't build
  "queued_at" : "2013-02-12T21:33:30Z" // time build was queued
  "start_time" : "2013-02-12T21:33:38Z", // time build started running
  "stop_time" : "2013-02-12T21:34:01Z", // time build finished running
  "build_time_millis" : 23505,
  "lifecycle" : "finished",
  "outcome" : "failed",
  "status" : "failed",
  "retry_of" : null, // build_num of the build this is a retry of
  "previous" : { // previous build
    "status" : "failed",
    "build_num" : 21
  } ]

settings

Endpoint: /project/:username/:repository/settings

Get project settings

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.settings

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.settings

Example response

{
    "hall_notify_prefs": nil,
    "irc_password": nil,
    "default_branch": "master",
    "hipchat_notify": nil,
    "campfire_notify_prefs": nil,
    "campfire_room": nil,
    "irc_keyword": nil,
    "slack_api_token": nil,
    "parallel": 1,
    "github_user": nil,
    "github_permissions": {
        "admin": true,
        "push": true,
        "pull": true
    },
    "irc_server": nil,
    "heroku_deploy_user": nil,
    "dependencies": "",
    "slack_notify_prefs": nil,
    "ssh_keys": [

    ],
    "extra": "",
    "followed": true,
    "branches": {
        "master": {
            "running_builds": [
                {
                    "added_at": "2014-06-05T17:22:52.779Z",
                    "pushed_at": "2014-06-05T17:22:52.518Z",
                    "vcs_revision": "66d398cb635c5f4dd666dd1526bda5894d1246e4",
                    "build_num": 6,
                    "status": "not_running",
                    "outcome": nil
                }
            ]
        }
    },
    "campfire_token": nil,
    "hipchat_notify_prefs": nil,
    "test": "",
    "compile": "",
    "hipchat_room": nil,
    "slack_channel": nil,
    "slack_subdomain": nil,
    "vcs_url": "https://github.com/Shopify/google_auth",
    "flowdock_api_token": nil,
    "hall_room_api_token": nil,
    "slack_webhook_url": nil,
    "irc_username": nil,
    "hipchat_api_token": nil,
    "campfire_subdomain": nil,
    "has_usable_key": true,
    "setup": "",
    "irc_channel": nil,
    "feature_flags": {
        "build_GH1157_container_oriented_ui": nil,
        "set-github-status": true
    },
    "irc_notify_prefs": nil
}

add_envvar

Endpoint: /project/:username/:project/envvar

Creates a new environment variable for a project

environment = { name: 'foo', value: 'bar' }

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.add_envvar environment

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.add_envvar environment

Example response

{"name":"foo","value":"xxxx"}

delete_envvar

Endpoint: /project/:username/:project/envvar

Deletes an environment variable for a project

envvar = 'SECRET_CI_TOKEN'

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.delete_envvar envvar

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.delete_envvar envvar

Example response

{"message": "ok"}

ssh_key

Endpoint: /project/:username/:repository/ssh-key

Creates an ssh key that will be used to access the external system identified by the hostname parameter for SSH key-based authentication.

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.ssh_key 'RSA private key', 'hostname'

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.ssh_key 'RSA private key', 'hostname'

Example response

Empty response body with a 200 OK successful response code

""

unfollow

Endpoint: /project/:username/:repository/unfollow

Unfollow a project

# Use global config with token for user
project = CircleCi::Project.new 'username', 'reponame'
res = project.unfollow

# Use a different config with another user token
project = CircleCi::Project.new 'username', 'reponame', 'github', other_project_config
project.unfollow

Example response

{
    "followed": false
}

Build

artifacts

Endpoint: /project/:username/:repository/:build/artifacts

Artifacts produced by the build, returns an array of artifact details

# Use global config with token for user
build = CircleCi::Build.new 'username', 'reponame', nil, 'build'
res = build.artifacts

# Use a different config with another user token
build = CircleCi::Build.new 'username', 'reponame', nil, 'build', other_build_config
build.artifacts

[
  {
    node_index: 0,
    path: "/tmp/circle-artifacts.NHQxLku/cherry-pie.png",
    pretty_path: "$CIRCLE_ARTIFACTS/cherry-pie.png",
    url: "https://circleci.com/gh/circleci/mongofinil/22/artifacts/0/tmp/circle-artifacts.NHQxLku/cherry-pie.png"
  },
  {
    node_index: 0,
    path: "/tmp/circle-artifacts.NHQxLku/rhubarb-pie.png",
    pretty_path: "$CIRCLE_ARTIFACTS/rhubarb-pie.png",
    url: "https://circleci.com/gh/circleci/mongofinil/22/artifacts/0/tmp/circle-artifacts.NHQxLku/rhubarb-pie.png"
  }
]

cancel

Endpoint: /project/:username/:repository/:build/cancel

Cancels the build, returns a summary of the build.

# Use global config with token for user
build = CircleCi::Build.new 'username', 'reponame', nil, 'build'
res = build.cancel

# Use a different config with another user token
build = CircleCi::Build.new 'username', 'reponame', nil, 'build', other_build_config
build.cancel

Example response

{
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/26",
  "build_num" : 26,
  "branch" : "master",
  "vcs_revision" : "59c9c5ea3e289f2f3b0c94e128267cc0ce2d65c6",
  "committer_name" : "Allen Rohner",
  "committer_email" : "arohner@gmail.com",
  "subject" : "Merge pull request #6 from dlowe/master"
  "body" : "le bump", // commit message body
  "why" : "retry", // short string explaining the reason we built
  "dont_build" : null, // reason why we didn't build, if we didn't build
  "queued_at" : "2013-05-24T19:37:59.095Z" // time build was queued
  "start_time" : null, // time build started running
  "stop_time" : null, // time build finished running
  "build_time_millis" : null,
  "username" : "circleci",
  "reponame" : "mongofinil",
  "lifecycle" : "queued",
  "outcome" : "canceled",
  "status" : "canceled",
  "canceled" : true,
  "retry_of" : 25, // build_num of the build this is a retry of
  "previous" : { // previous build
    "status" : "success",
    "build_num" : 25
  }
}

get

Endpoint: /project/:username/:repository/:build

Full details for a single build, including the output for all actions. The response includes all of the fields from the build summary.

# Use global config with token for user
build = CircleCi::Build.new 'username', 'reponame', nil, 'build'
res = build.get

# Use a different config with another user token
build = CircleCi::Build.new 'username', 'reponame', nil, 'build', other_build_config
build.get

Example response

{
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/22",
  "build_num" : 22,
  "steps" : [ {
    "name" : "configure the build",
    "actions" : [ {
      "bash_command" : null,
      "run_time_millis" : 1646,
      "start_time" : "2013-02-12T21:33:38Z",
      "end_time" : "2013-02-12T21:33:39Z",
      "name" : "configure the build",
      "command" : "configure the build",
      "exit_code" : null,
      "out" : [ ],
      "type" : "infrastructure",
      "index" : 0,
      "status" : "success",
    } ] },
    "name" : "lein2 deps",
    "actions" : [ {
      "bash_command" : "lein2 deps",
      "run_time_millis" : 7555,
      "start_time" : "2013-02-12T21:33:47Z",
      "command" : "((lein2 :deps))",
      "messages" : [ ],
      "step" : 1,
      "exit_code" : 0,
      "out" : [ {
        "type" : "out",
        "time" : "2013-02-12T21:33:54Z",
        "message" : "Retrieving org/clojure ... from clojars\r\n"
      } ],
      "end_time" : "2013-02-12T21:33:54Z",
      "index" : 0,
      "status" : "success",
      "type" : "dependencies",
      "source" : "inference",
      "failed" : null
    } ] },
    "name" : "lein2 trampoline midje",
    "actions" : [ {
      "bash_command" : "lein2 trampoline midje",
      "run_time_millis" : 2310,
      "continue" : null,
      "parallel" : true,
      "start_time" : "2013-02-12T21:33:59Z",
      "name" : "lein2 trampoline midje",
      "command" : "((lein2 :trampoline :midje))",
      "messages" : [ ],
      "step" : 6,
      "exit_code" : 1,
      "out" : [ {
        "type" : "out",
        "time" : "2013-02-12T21:34:01Z",
        "message" : "'midje' is not a task. See 'lein help'.\r\n\r\nDid you mean this?\r\n         do\r\n"
      }, {
        "type" : "err",
        "time" : "2013-02-12T21:34:01Z",
        "message" : "((lein2 :trampoline :midje)) returned exit code 1"
      } ],
      "end_time" : "2013-02-12T21:34:01Z",
      "index" : 0,
      "status" : "failed",
      "timedout" : null,
      "infrastructure_fail" : null,
      "type" : "test",
      "source" : "inference",
      "failed" : true
    } ]
  } ],
}

retry

Endpoint: /project/:username/:repository/:build/retry

Retries the build, returns a summary of the new build.

# Use global config with token for user
build = CircleCi::Build.new 'username', 'reponame', nil, 'build'
res = build.retry

# Use a different config with another user token
build = CircleCi::Build.new 'username', 'reponame', nil, 'build', other_build_config
build.retry

Example response

{
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/23",
  "build_num" : 23,
  "branch" : "master",
  "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
  "committer_name" : "Allen Rohner",
  "committer_email" : "arohner@gmail.com",
  "subject" : "Don't explode when the system clock shifts backwards",
  "body" : "", // commit message body
  "why" : "retry", // short string explaining the reason we built
  "dont_build" : null, // reason why we didn't build, if we didn't build
  "queued_at" : "2013-04-12T21:33:30Z" // time build was queued
  "start_time" : "2013-04-12T21:33:38Z", // time build started running
  "stop_time" : "2013-04-12T21:34:01Z", // time build finished running
  "build_time_millis" : 23505,
  "lifecycle" : "queued",
  "outcome" : null,
  "status" : "queued",
  "retry_of" : 22, // build_num of the build this is a retry of
  "previous" : { // previous build
    "status" : "failed",
    "build_num" : 22
  }

tests

Endpoint: /project/:username/:repository/:build/tests

Tests endpoint to get the recorded tests for a build. Will return an array of the tests ran and some details.

# Use global config with token for user
build = CircleCi::Build.new 'username', 'reponame', nil, 'build'
res = build.tests

# Use a different config with another user token
build = CircleCi::Build.new 'username', 'reponame', nil, 'build', other_build_config
build.tests

[
  {
    "message" => nil,
    "file" => "spec/unit/user_spec.rb",
    "source" => "rspec",
    "run_time" => 0.240912,
    "result" => "success",
    "name" => "user creation",
    "classname"=> "spec.unit.user_spec"
  },
  {
    "message" => "Unable to update user",
    "file" => "spec/unit/user_spec.rb",
    "source"=>"rspec",
    "run_time"=>5.58533,
    "result"=>"failure",
    "name"=>"user update",
    "classname"=>"spec.unit.user_spec"
  }
]

recent_builds

get_recent_builds

Endpoint: /recent-builds

Build summary for each of the last 30 recent builds, ordered by build_num.

# Use global config with token for user
recent = CircleCi::RecentBuilds.new
res = recent.get

# Params of limit and offset can be passed in
res = recent.get limit: 10, offset: 50

# Use a different config with another user token
recent = CircleCi::RecentBuilds.new other_builds_config
recent.get

[ {
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/22",
  "build_num" : 22,
  "branch" : "master",
  "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
  "committer_name" : "Allen Rohner",
  "committer_email" : "arohner@gmail.com",
  "subject" : "Don't explode when the system clock shifts backwards",
  "body" : "", // commit message body
  "why" : "github", // short string explaining the reason we built
  "dont_build" : null, // reason why we didn't build, if we didn't build
  "queued_at" : "2013-02-12T21:33:30Z" // time build was queued
  "start_time" : "2013-02-12T21:33:38Z", // time build started
  "stop_time" : "2013-02-12T21:34:01Z", // time build finished
  "build_time_millis" : 23505,
  "username" : "circleci",
  "reponame" : "mongofinil",
  "lifecycle" : "finished", // :queued, :scheduled, :not_run, :not_running, :running or :finished
  "outcome" : "failed", // :canceled, :infrastructure_fail, :timedout, :failed, :no_tests or :success
  "status" : "failed", // :retried, :canceled, :infrastructure_fail, :timedout, :not_run, :running, :failed, :queued, :scheduled, :not_running, :no_tests, :fixed, :success
  "retry_of" : null, // build_num of the build this is a retry of
  "previous" : { // previous build
    "status" : "failed",
    "build_num" : 21
  }, ... ]

Tests

Tests are ran using Rspec and VCR for API interaction recording. Run using rake or rspec. Please add tests for any new features or endpoints added if you are contributing. Code styling is enforced with RuboCop and uses a checked in .rubocop.yml for this project.

Tests are using a live CircleCi API token for this repository. Any tests should be using this key, which is in the .env file. You should not have to do anything outside of writing the tests against this repository.

circleci

Development

circleci

Install

Usage

Documentation

Configuring

Global Config

Config Object

API Versioning

VCS Type

API Endpoints

User

heroku_key

me

Project

all

build_branch

build_ssh_key

clear_cache

delete_checkout_key

enable

envvar

follow

get_checkout_key

list_checkout_keys

new_checkout_key

recent_project_builds

recent_builds_branch

settings

add_envvar

delete_envvar

ssh_key

unfollow

Build

artifacts

cancel

get

retry

tests

recent_builds

get_recent_builds

Tests