circleci
Circle CI API Wrapper
Install
gem install 'circleci'
or with Bundler
gem 'circleci'
Usage
Configuring
Configure using an API token from Circle
CircleCi.configure do |config|
config.token = 'my-token'
end
User
CircleCi::User.me
Provides information about the signed in user.
res = CircleCi::User.me
res.succes? # True
res.body
Example response
{
"basic_email_prefs" : "smart", // can be "smart", "none" or "all"
"login" : "pbiggar" // your github username
}
Project
CircleCi::Project.all
List of all the repos you have access to on Github, with build information organized by branch.
res = CircleCi::Project.all
res.success?
res.body
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
}
}
} ]
CircleCi::Project.recent_builds
Build summary for each of the last 30 recent builds, ordered by build_num.
res = CircleCi::Project.recent_builds 'username', 'reponame'
res.success?
res.body
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" : "[email protected]",
"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
} ]
CircleCi::Project.recent_builds_branch
Build summary for each of the last 30 recent builds for a specific branch, ordered by build_num.
res = CircleCi::Project.recent_builds_branch 'username', 'reponame', 'branch'
res.success?
res.body
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" : "[email protected]",
"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
} ]
CircleCi::Project.clear_cache
Clears the cache for a project
res = CircleCi::Project.clear_cache
res.body['status']
Example response
{
"status" : "build caches deleted"
}
CircleCI::Project.build_branch
Build a specific branch of a project
res = CircleCi::Project.build_branch 'username', 'reponame', 'branch'
res.body['status'] # Not running
res.body['build_url'] # Get url of build
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" : "[email protected]"
},
"vcs_revision" : "f932ea1b564ceaaa8cdba06b1bb93e1869a9a905",
"build_num" : 77,
"infrastructure_fail" : false,
"ssh_enabled" : null,
"committer_email" : "[email protected]",
"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" : "[email protected]",
"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" : "[email protected]"
} ],
"outcome" : null,
"vcs_url" : "https://github.com/ad2games/soapy_cake",
"author_name" : "Harald Wartig",
"node" : null,
"canceled" : false,
"author_email" : "[email protected]"
}
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
CircleCi::Build.get
Full details for a single build, including the output for all actions. The response includes all of the fields from the build summary.
res = CircleCi::Build.get 'username', 'repo', 'build #'
res.success?
res.body
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
} ]
} ],
}
CircleCi::Build.retry
Retries the build, returns a summary of the new build.
res = CircleCi::Build.retry 'username', 'repo', 'build #'
res.success?
res.body['status'] # 'queued'
res.body
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" : "[email protected]",
"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
}
#### CircleCi::Build.cancel
Cancels the build, returns a summary of the build.
```ruby
res = CircleCi::Build.cancel 'username', 'repo', 'build #'
res.success?
res.body['status'] # 'canceled'
res.body['outcome'] # 'canceled'
res.body['canceled'] # true
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" : "[email protected]",
"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
}
}
CircleCi::Build.artifacts
Artifacts produced by the build, returns an array of artifact details
res = CircleCi::Build.artifacts 'username', 'repo', 'build #'
res.success?
res.body
[
{
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"
}
]
CircleCi::Build.tests
Tests endpoint to get the recorded tests for a build. Will return an array of the tests ran and some details.
res = CircleCi::Build.tests 'username', 'repo', 'build #'
res.success?
res.body
[
{
"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"
}
]
CircleCi.organization
Recent builds for an entire organization
res = CircleCi.organization 'my-org'
res.succes?
res.body
[
{
"dont_build":null,
"committer_name":"Chavez",
"usage_queued_at":"2014-04-12T10:29:59.352Z",
"branch":"master",
"body":"Update Missing ''e'' in CircleCi in README.md",
"author_date":"2014-03-12T23:14:53Z",
"node":[
{
"username":"ubuntu",
"ssh_enabled":null,
"port":64721,
"public_ip_addr":"54.82.224.94"
}
],
"committer_date":"2014-03-12T23:14:53Z",
"compare":null,
"retries":null,
"parallel":1,
"committer_email":"[email protected]",
"build_time_millis":16308,
"why":"retry",
"author_email":"[email protected]",
"ssh_enabled":null,
"start_time":"2014-04-12T10:29:59.587Z",
"stop_time":"2014-04-12T10:30:15.895Z",
"lifecycle":"finished",
"user":{
"is_user":true,
"login":"hwartig",
"name":"Harald Wartig",
"email":"[email protected]"
},
"subject":"Merge pull request #4 from Alex-Poon/master",
"messages":[
],
"job_name":null,
"retry_of":1,
"previous_successful_build":{
"build_time_millis":37685,
"status":"success",
"build_num":1
},
"outcome":"success",
"status":"success",
"vcs_revision":"f33617404dc392ddd676fdde87cd5c87369e1857",
"build_num":2,
"username":"hwartigcom",
"vcs_url":"https://github.com/hwartigcom/circleci",
"timedout":false,
"previous":{
"build_time_millis":37685,
"status":"success",
"build_num":1
},
"canceled":false,
"infrastructure_fail":false,
"failed":null,
"reponame":"circleci",
"build_url":"https://circleci.com/gh/hwartigcom/circleci/2",
"feature_flags":{
},
"author_name":"Chavez",
"queued_at":"2014-04-12T10:29:59.517Z"
},
{
"dont_build":null,
"committer_name":"Chavez",
"usage_queued_at":"2014-04-08T06:58:09.522Z",
"branch":"master",
"body":"Update Missing ''e'' in CircleCi in README.md",
"author_date":"2014-03-12T23:14:53Z",
"node":[
{
"username":"ubuntu",
"ssh_enabled":null,
"port":64775,
"public_ip_addr":"54.198.9.232"
}
],
"committer_date":"2014-03-12T23:14:53Z",
"compare":null,
"retries":[
2
],
"parallel":1,
"committer_email":"[email protected]",
"build_time_millis":37685,
"why":"first-build",
"author_email":"[email protected]",
"ssh_enabled":null,
"start_time":"2014-04-08T06:58:09.868Z",
"stop_time":"2014-04-08T06:58:47.553Z",
"lifecycle":"finished",
"user":{
"is_user":true,
"login":"hwartig",
"name":"Harald Wartig",
"email":"[email protected]"
},
"subject":"Merge pull request #4 from Alex-Poon/master",
"messages":[
],
"job_name":null,
"retry_of":null,
"previous_successful_build":null,
"outcome":"success",
"status":"success",
"vcs_revision":"f33617404dc392ddd676fdde87cd5c87369e1857",
"build_num":1,
"username":"hwartigcom",
"vcs_url":"https://github.com/hwartigcom/circleci",
"timedout":false,
"previous":null,
"all_commit_details":[
{
"committer_name":"Chavez",
"body":"Update Missing ''e'' in CircleCi in README.md",
"author_date":"2014-03-12T23:14:53Z",
"committer_date":"2014-03-12T23:14:53Z",
"commit_url":"https://github.com/hwartigcom/circleci/commit/f33617404dc392ddd676fdde87cd5c87369e1857",
"committer_email":"[email protected]",
"author_email":"[email protected]",
"subject":"Merge pull request #4 from Alex-Poon/master",
"commit":"f33617404dc392ddd676fdde87cd5c87369e1857",
"author_name":"Chavez"
}
],
"canceled":false,
"infrastructure_fail":false,
"failed":null,
"reponame":"circleci",
"build_url":"https://circleci.com/gh/hwartigcom/circleci/1",
"feature_flags":{
},
"author_name":"Chavez",
"queued_at":"2014-04-08T06:58:09.739Z"
}
]
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.
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.