circleci 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c271b9c2906c8719ddbe6aaeac6e81629d9645e8
-  data.tar.gz: c8abb1f29b0977cb64577db02d530b03911c1357
+  metadata.gz: 01d1ecdf5dd5c7751ba1b8d5a02aac75129a3ff3
+  data.tar.gz: 29f32045901558cb42e4c25e68d4bdeb5569cf5f
 SHA512:
-  metadata.gz: b260e331a7d82d2ae8f5b437fe1672eb045680e15fc85235d4bd1825527bd41cedbf791fb0928776cb2c881977920a468bad50a456e433db7a1b213aa1ada1ab
-  data.tar.gz: 9befc960bc2353e0410e308375ea5a9b4677a152bcd205c72b7e69a1434f6ffbfaccd887e21ca1da1e496970cf3953d2d11770b17e83806a9dda253ab71e921e
+  metadata.gz: 964f61a6e7976946c3cd8d14082d2625d28f9e6fc55a086ce33c22c84bdc27a76d7cc7bd18901770ccc94386903822c3599e6250d3fd0851d79fee6d7edbab0b
+  data.tar.gz: 3e41c32238ab6fc370a221376200bd8e0289fd9ff838d4dac363e8f4f2cc37842b6572d8d6e6114f109c653ead394fb33d2298562796447f3b9cfcb345da0bb7

data/README.md

@@ -8,6 +8,11 @@
 
 Circle CI API Wrapper. Requires ruby `>= 2.0.0`.
 
+**Version 2.x has breaking changes from v1.x**
+> Please use branch v-1.1.0 or tag v1.1.0 for previous 1.x version of
+> the gem until you can update to the latest version. 1.x will not be supported
+> in the longer term.
+
 ## Install
 
 ```ruby
@@ -22,8 +27,14 @@ gem 'circleci'
 
 ## Usage
 
+### Documentation
+
+Documentation can be found on [rubydoc][docs] or in this README
+
 ### Configuring
 
+#### Global Config
+
 Configure using an API token from Circle
 
 ```ruby
@@ -71,6 +82,67 @@ CircleCi.configure do |config|
 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.
+
+```ruby
+# 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.
+
+```ruby
+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
+
+```ruby
+# 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](#user)
@@ -88,7 +160,7 @@ end
   * [Get Checkout Key](#get_checkout_key)
   * [List Checkout Keys](#list_checkout_keys)
   * [New Checkout Key](#new_checkout_key)
-  * [Recent Builds](#project_recent_builds)
+  * [Recent Project Builds](#recent_project_builds)
   * [Recent Builds Branch](#recent_builds_branch)
   * [Settings](#settings)
   * [Set Envvar](#set_envvar)
@@ -101,7 +173,7 @@ end
   * [Retry](#retry)
   * [Tests](#tests)
 * [Recent Builds](#recent_builds)
-  * [Get](#recent_builds_get)
+  * [Get Recent Builds](#get_recent_builds)
 
 ### [User](#user)
 
@@ -111,9 +183,13 @@ Endpoint: `/user/heroku-key`
 
 Adds your Heroku API key to CircleCI.
 ```ruby
-res = CircleCi::User.heroku_key 'your-api-key'
-res.success? # True
-res.body
+# 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
@@ -130,9 +206,13 @@ Endpoint: `/me`
 Provides information about the signed in user.
 
 ```ruby
-res = CircleCi::User.me
-res.success? # True
-res.body
+# 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
@@ -153,9 +233,13 @@ Endpoint: `/projects`
 List of all the repos you have access to on Github, with build information organized by branch.
 
 ```ruby
-res = CircleCi::Project.all
-res.success?
-res.body
+# 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
@@ -203,23 +287,30 @@ Endpoint: `/project/:username/:repository/tree/:branch`
 Build a specific branch of a project
 
 ```ruby
-res = CircleCi::Project.build_branch 'username', 'reponame', 'branch'
-res.body['status'] # Not running
-res.body['build_url'] # Get url of build
+# Use global config with token for user
+project = CircleCi::Project.new 'username', 'reponame'
 
-# Passing build parameters in the post body
-build_params = { build_parameters: { 'MY_TOKEN' => '123asd123asd' } }
-res = CircleCi::Project.build_branch 'username', 'reponame', 'branch', {}, build_params
-res.body['status'] # Not running
-res.body['build_url'] # Get url of build
+# Get recent failed builds with a filter parameter
+failed_builds = project.build_branch 'branch'
 
 # Adding URL params for revision or parallel
 params = { revision: 'fda12345asdf', parallel: 2 }
-res = CircleCi::Project.build_branch 'username', 'reponame', 'branch', params
+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', other_project_config
+project.build_branch 'branch'
 ```
 
+
 Example response
 
 ```javascript
@@ -311,8 +402,13 @@ Endpoint: `/project/:username/:repository/:build_num/ssh-users`
 Adds a user to the build's SSH permissions.
 
 ```ruby
-res = CircleCi::Project.build_ssh_key 'username', 'repo', 'RSA private key', 'hostname'
-res.success?
+# 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', other_project_config
+project.build_ssh_key 'username', 'repo', 'RSA private key', 'hostname'
 ```
 
 Example response
@@ -329,8 +425,13 @@ Endpoint: `/project/:username/:repository/build-cache`
 Clears the cache for a project
 
 ```ruby
-res = CircleCi::Project.clear_cache
-res.body['status']
+# 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', other_project_config
+project.clear_cache
 ```
 
 Example response
@@ -347,9 +448,13 @@ Endpoint: `/project/:username/:repository/checkout-key/:fingerprint`
 
 Delete a checkout key for a project by supplying the fingerprint of the key.
 ```ruby
-res = CircleCi::Project.delete_checkout_key 'username', 'reponame', 'fingerprint'
-res.success?
-res.body
+# 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', other_project_config
+project.delete_checkout_key 'fingerprint'
 ```
 
 Example response
@@ -366,8 +471,13 @@ Enable a project in CircleCI. Causes a CircleCI SSH key to be added to
 the GitHub. Requires admin privilege to the repository.
 
 ```ruby
-res = CircleCi::Project.enable 'username', 'reponame'
-res.success?
+# 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', other_project_config
+project.enable
 ```
 
 Example response
@@ -454,8 +564,13 @@ Endpoint: `/project/:username/:project/envvar`
 Get a list of environment variables for a project
 
 ```ruby
-res = CircleCi::Project.envvar 'username', 'repo'
-res.success?
+# 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', other_project_config
+project.envvar
 ```
 
 Example response
@@ -471,8 +586,13 @@ Endpoint: `/project/:username/:repository/follow`
 Follow a project
 
 ```ruby
-res = CircleCi::Build.follow 'username', 'repo'
-res.success?
+# 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', other_project_config
+project.follow
 ```
 
 Example response
@@ -489,10 +609,15 @@ Example response
 Endpoint: `/project/:username/:repository/checkout-key/:fingerprint`
 
 Get a checkout key for a project by supplying the fingerprint of the key.
+
 ```ruby
-res = CircleCi::Project.get_checkout_key 'username', 'reponame', 'fingerprint'
-res.success?
-res.body
+# 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', other_project_config
+project.get_checkout_key 'fingerprint
 ```
 
 Example response
@@ -514,8 +639,13 @@ Endpoint: `/project/#{username}/#{project}/checkout-key`
 List checkout keys
 
 ```ruby
-res = CircleCi::Project.checkout_keys 'username', 'repo'
-res.success?
+# 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', other_project_config
+project.checkout_keys
 ```
 
 Example response
@@ -538,10 +668,15 @@ 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`.
+
 ```ruby
-res = CircleCi::Project.new_checkout_key 'username', 'reponame', 'deploy-key'
-res.success?
-res.body
+# 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', other_project_config
+project.new_checkout_key 'deploy-key
 ```
 
 Example response
@@ -556,23 +691,26 @@ Example response
 }
 ```
 
-#### [recent_builds](#project_recent_builds)
+#### [recent_project_builds](#recent_project_builds)
 
 Endpoint: `/project/:username/:repository`
 
 Build summary for each of the last 30 recent builds, ordered by build_num.
 
 ```ruby
-res = CircleCi::Project.recent_builds 'username', 'reponame'
+# Use global config with token for user
+project = CircleCi::Project.new 'username', 'reponame'
+res = project.recent_builds
 
 # Use params to filter by status
-# res = CircleCi::Project.recent_builds 'username', 'reponame', filter: 'failed'
+res = project.recent_builds filter: 'failed'
 
 # Use params to limit and give an offset
-# res = CircleCi::Project.recent_builds 'username', 'reponame', limit: 10, offset: 50
+res = project.recent_builds limit: 10, offset: 50
 
-res.success?
-res.body
+# Use a different config with another user token
+project = CircleCi::Project.new 'username', 'reponame', other_project_config
+project.recent_builds
 ```
 
 Example response
@@ -611,9 +749,13 @@ Endpoint: `/project/:username/:repository/tree/:branch`
 Build summary for each of the last 30 recent builds for a specific branch, ordered by build_num.
 
 ```ruby
-res = CircleCi::Project.recent_builds_branch 'username', 'reponame', 'branch'
-res.success?
-res.body
+# Use global config with token for user
+project = CircleCi::Project.new 'username', 'reponame'
+res = project.recent_builds_branch 'branch'
+
+# Use a different config with another user token
+project = CircleCi::Project.new 'username', 'reponame', other_project_config
+project.recent_builds_branch 'branch'
 ```
 
 Example response
@@ -652,8 +794,13 @@ Endpoint: `/project/:username/:repository/settings`
 Get project settings
 
 ```ruby
-res = CircleCi::Project.settings 'username', 'repo'
-res.success?
+# 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', other_project_config
+project.settings
 ```
 
 Example response
@@ -731,8 +878,14 @@ Creates a new environment variable for a project
 
 ```ruby
 environment = { name: 'foo', value: 'bar' }
-res = CircleCi::Project.set_envvar 'username', 'repo', environment
-res.success?
+
+# Use global config with token for user
+project = CircleCi::Project.new 'username', 'reponame'
+res = project.set_envvar environment
+
+# Use a different config with another user token
+project = CircleCi::Project.new 'username', 'reponame', other_project_config
+project.set_envvar environment
 ```
 
 Example response
@@ -749,8 +902,13 @@ Creates an ssh key that will be used to access the external system identified
 by the hostname parameter for SSH key-based authentication.
 
 ```ruby
-res = CircleCi::Project.ssh_key 'username', 'repo', 'RSA private key', 'hostname'
-res.success?
+# 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', other_project_config
+project.ssh_key 'RSA private key', 'hostname'
 ```
 
 Example response
@@ -767,8 +925,13 @@ Endpoint: `/project/:username/:repository/unfollow`
 Unfollow a project
 
 ```ruby
-res = CircleCi::Build.unfollow 'username', 'repo'
-res.success?
+# 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', other_project_config
+project.unfollow
 ```
 
 Example response
@@ -788,9 +951,13 @@ Endpoint: `/project/:username/:repository/:build/artifacts`
 Artifacts produced by the build, returns an array of artifact details
 
 ```ruby
-res = CircleCi::Build.artifacts 'username', 'repo', 'build #'
-res.success?
-res.body
+# 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
 ```
 
 ```javascript
@@ -817,11 +984,13 @@ Endpoint: `/project/:username/:repository/: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
+# 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
@@ -864,9 +1033,13 @@ 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.
 
 ```ruby
-res = CircleCi::Build.get 'username', 'repo', 'build #'
-res.success?
-res.body
+# 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
@@ -953,10 +1126,13 @@ Endpoint: `/project/:username/:repository/:build/retry`
 Retries the build, returns a summary of the new build.
 
 ```ruby
-res = CircleCi::Build.retry 'username', 'repo', 'build #'
-res.success?
-res.body['status'] # 'queued'
-res.body
+# 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
@@ -996,9 +1172,13 @@ Tests endpoint to get the recorded tests for a build. Will return an array of
 the tests ran and some details.
 
 ```ruby
-res = CircleCi::Build.tests 'username', 'repo', 'build #'
-res.success?
-res.body
+# 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
 ```
 
 ```javascript
@@ -1024,22 +1204,25 @@ res.body
 ]
 ```
 
-### [Recent Builds](#recent_builds)
+### [recent_builds](#recent_builds)
 
-#### [get](#recent_builds_get)
+#### [get_recent_builds](#get_recent_builds)
 
 Endpoint: `/recent-builds`
 
 Build summary for each of the last 30 recent builds, ordered by build_num.
 
 ```ruby
-res = CircleCi::RecentBuilds.get
+# Use global config with token for user
+recent = CircleCi::RecentBuilds.new
+res = recent.get
 
 # Params of limit and offset can be passed in
-# res = CircleCi::RecentBuilds.get limit: 10, offset: 50
+res = recent.get limit: 10, offset: 50
 
-res.success?
-res.body
+# Use a different config with another user token
+recent = CircleCi::RecentBuilds.new other_builds_config
+recent.get
 ```
 
 ```javascript
@@ -1081,3 +1264,6 @@ 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.
+
+
+[docs]: http://www.rubydoc.info/gems/circleci