Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Travis CI API Client

Ruby client for the Travis CI API, version 3.


You can install it as a RubyGem via:

$ gem install travis-client

Note that it does conflict with travis.rb at the moment, as both of them add a travis/client file. It is highly recommended to use Bundler to avoid accidentally loading the wrong gem in your scripts.

Getting Started

This library has two general ways to use it. An interface based on globals, that should feel quite natural to Ruby developers:

require 'travis/client'
Travis.connect # call before interacting with anything else
repository = Travis::Repository.find(slug: 'travis-ci/travis-web')

Or an approach based on sessions, which helps avoiding global state, and easily allows multiple connections in parallel with different credentials or even different Travis CI installations:

require 'travis/client'
connection =
session    = connection.create_session
repository = session.find_repository(slug: 'travis-ci/travis-web')

Objects returned by Repository.find and find_repository are identical. You can access the underlying session object used by Travis::Repository.find via Travis.session.

Each session will have its own cache, and HTTP connections. Recreating connection objects (by either calling Travis.connect or frequently should be avoided, as it will rebuild internal factories based on the API auto-discovery.

Both and Travis.connect accept the following options:

  • endpoint: URI for the entry point to the Travis CI API, defaults to Set this to for the Pro version of Travis CI, for Travis CI Enterprise (assuming your Enterprise web UI is reachable under
  • request_headers: Allows defining additional headers to be sent to Travis CI with every HTTP request. Can also be used to override headers, like User-Agent.
  • access_token: API access token to use for authentication.

Advanced Features


You'll need an API token to authenticate. The library currently does not offer a way to obtain such a token, the easiest way to obtain such a token is to visit the developer pages and hover over the token in a code example and copy the value. Please note that there are separate tokens for and, and you will have to use the appropriate token depending on which API you interact with.

Alternatively, you can use the token command from the CLI.

# connecting to with a token stored in TRAVIS_TOKEN env var
Travis.connect(access_token: ENV['TRAVIS_TOKEN'])

# connecting to with a token stored in TRAVIS_PRO_TOKEN env var
Travis.connect(api_endpoint: '' access_token: ENV['TRAVIS_PRO_TOKEN'])

When using multiple sessions, the token may either be passed to the connection (in which case it will be used fo all sessions) or each session individually:

connection = ENV['TRAVIS_TOKEN'])
puts connection.create_session.current_user.login

# for a list of tokens, output which user is associated with it
access_tokens = [ ... list of tokens ... ]
connection    = '')
access_tokens.each do |token|
  session     = connection.create_session(access_token: token)
  puts session.current_user.login

Caching and Session Renewal

Each session will have it's own cache. If you have long running processes and concerns about cache size or stale caches, then the easiest and cleanest way to deal with this is to discard session objects after a while and not hold on to any entities associated with it.

In a web application (like Rails or Sinatra), it is recommended to use a new session per request, or per background job. This will also greatly decrease threading issues (see below).

require 'sinatra'
require 'travis/client'

# create connection once, but create one session per request
connection = ENV['TRAVIS_TOKEN'])
before { @travis = connection.create_session }

get '/' do
  "Hello, #{}!"

If you do have to clear a session's cache, you can do so via session.response_cache.clear or Travis.clear_cache. However, this is not recommended and any response objects that might still be referenced somewhere will probably end up with a mix of outdated and recent data.

Thread Safety

Neither Travis.connect nor loading resources is currently thread-safe, with the notable exception of Connection#create_session. You still can (and should) use it in a threaded environment.

To use with a threaded environment:

  • Initialize a new connection once, via
  • From this connection, create one session per thread via #create_session.

Example that fetches repositories in parallel:

require 'travis/client'

repositories = ['travis-ci/travis-web', 'travis-ci/travis-api', 'sinatra/sinatra']
connection   =
threads      = do |slug| { connection.create_session.find_repository(slug: slug) }

threads.each do |thread|

Permission Checks

You can check permissions on any entity object via the permission? method:

Travis::User.current.permission? :sync                    # => true
Travis::Owner.find(login: 'svenfuchs').permission? :sync  # => false

user = Travis::User.current
user.sync if user.permission? :sync

You can find a full list of permission in the developer documentation.

Eager Loading

The following code will trigger two HTTP requests, one to fetch the repository, and one to fetch the last build on the default branch:

repository = Travis::Repository.find(slug: 'travis-ci/travis-api')
puts repository.default_branch.last_build.state

You can reduce this to a single HTTP request by eager loading branch.last_build:

repository = Travis::Repository.find(slug: 'travis-ci/travis-api', include: 'branch.last_build')
puts repository.default_branch.last_build.state


Each object representing a collection is an Enumerable and will handle pagination in a transparent way:

# will automatically paginate if necessary { |branch| }

Just like with missing attributes, the code will trigger any additional HTTP requests lazily, but only once, so exiting a loop over a collection prematurely (for instance, by using break or return) might reduce the number of HTTP requests.

You can also use the limit, offset and sort parameters to fine-tune requests.

Request Hooks and Instrumentation

You can add hooks that will trigger before or after any HTTP request:

Travis.before_request { |r| puts "** #{r.request_method} #{r.uri}"}
Travis::Repository.find(slug: 'rails/rails')

You can use the meta_data hash to share data between hooks:

Travis.before_request do |request|
  request.meta_data[:start] =

Travis.after_request do |request|
  duration = - request.meta_data[:start]
  puts "** #{request.request_method} #{request.uri} - #{request.response.status} - #{duration}s"

Travis::Repository.find(slug: 'rails/rails')


Ruby client library for Travis CI API







No packages published