# The Travis Client [![Build Status](https://travis-ci.org/travis-ci/travis.png?branch=master)](https://travis-ci.org/travis-ci/travis) The [travis gem](https://rubygems.org/gems/travis) includes both a command line client and a Ruby library to interface with a Travis CI service. Both work with [travis-ci.org](https://travis-ci.org), [travis-ci.com](https://travis-ci.com) or any custom Travis CI setup you might have. ## Table of Contents * [Command Line Client](#command-line-client) * [Non-API Commands](#non-api-commands) * [`help`](#help) * [`version`](#version) * [General API Commands](#general-api-commands) * [`console`](#console) * [`endpoint`](#endpoint) * [`login`](#login) * [`raw`](#raw) * [`sync`](#sync) * [`token`](#token) * [`whatsup`](#whatsup) * [`whoami`](#whoami) * [Repository Commands](#repository-commands) * [`disable`](#disable) * [`enable`](#enable) * [`encrypt`](#encrypt) * [`history`](#history) * [`logs`](#logs) * [`open`](#open) * [`restart`](#restart) * [`show`](#show) * [`status`](#status) * [Ruby Library](#ruby-library) * [Authentication](#authentication) * [Using Pro](#using-pro) * [Entities](#entities) * [Stateful Entities](#stateful-entities) * [Repositories](#repositories) * [Builds](#builds) * [Jobs](#jobs) * [Artifacts](#artifacts) * [Users](#users) * [Commits](#commits) * [Workers](#workers) * [Dealing with Sessions](#dealing-with-sessions) * [Using Namespaces](#using-namespaces) * [Installation](#installation) * [Upgrading from travis-cli](#upgrading-from-travis-cli) * [Version History](#version-history) ## Command Line Client There are three types of commands: [Non-API Commands](#non-api-commands), [General API Commands](#general-api-commands) and [Repository Commands](#repository-commands). All commands take the form of `travis COMMAND [ARGUMENTS] [OPTIONS]`. You can get a list of commands by running [`help`](#help). ### Non-API Commands Every Travis command takes three global options: -h, --help Display help -i, --[no-]interactive be interactive and colorful -E, --[no-]explode don't rescue exceptions The `--help` option is equivalent to running `travis help COMMAND`. The `--interactive` options determines wether to include additional information and colors in the output or not (except on Windows, we never display colors on Windows, sorry). If you don't set this option explicitly, you will run in interactive mode if you invoke the command directly in a shell and in non-interactive mode if you pipe it somewhere. You probably want to use `--explode` if you are working on a patch for the Travis client, as it will give you the Ruby exception instead of a nice error message. #### `help` The `help` command will inform you about the arguments and options that the commands take, for instance: $ travis help help Usage: travis help [command] [options] -h, --help Display help -i, --[no-]interactive be interactive and colorful -E, --[no-]explode don't rescue exceptions Running `help` without a command name will give you a list of all available commands. #### `version` As you might have guessed, this command prints out the client's version. ### General API Commands API commands inherit all options from [Non-API Commands](#non-api-commands). Additionally, every API command understands the following options: -e, --api-endpoint URL Travis API server to talk to --pro short-cut for --api-endpoint 'https://api.travis-ci.com/' --org short-cut for --api-endpoint 'https://api.travis-ci.org/' -t, --token [ACCESS_TOKEN] access token to use --debug show API requests --adapter ADAPTER Faraday adapter to use for HTTP requests By default, [General API Commands](#general-api-commands) will talk to [api.travis-ci.org](https://api.travis-ci.org). You can change this by supplying `--pro` for [api.travis-ci.com](https://api.travis-ci.com) or `--api-endpoint` with your own endpoint. Note that all [Repository Commands](#repository-commands) will try to figure out the API endpoint to talk to automatically depending on the project's visibility on GitHub. You can supply an access token via `--token` if you want to make an authenticated call. If you don't have an access token stored for the API endpoint, it will remember it for subsequent requests. Keep in mind, this is not the "Travis token" used when setting up GitHub hooks (due to security). You probably don't have an access token handy right now. Don't worry, usually you won't use this option but instead just do a [`travis login`](#login). The `--debug` option will print HTTP requests to STDERR. Like `--explode`, this is really helpful when contributing to this project. There are many libraries out there to do HTTP requests in Ruby. You can switch amongst common ones with `--adapter`: $ travis show --adapter net-http ... $ gem install excon ... $ travis show --adapter excon ... #### `console` Running `travis console` gives you an interactive Ruby session with all the [entities](#entities) imported into global namespace. But why use this over just `irb -r travis`? For one, it will take care of authentication, setting the correct endpoint, etc, and it also allows you to pass in `--debug` if you are curious as to what's actually going on. $ travis console >> User.current => # >> Repository.find('sinatra/sinatra') => # >> _.last_build => # #### `endpoint` Just prints out the API endpoint you're talking to. $ travis endpoint API endpoint: https://api.travis-ci.org/ Handy for using it when working with shell scripts: $ curl "$(travis endpoint)/docs" > docs.html #### `login` The `login` command will, well, log you in. That way, all subsequent commands that run against the same endpoint will be authenticated. $ travis login We need your GitHub login to identify you. This information will not be sent to Travis CI, only to GitHub. The password will not be displayed. Try running with --github-token or --auto if you don't want to enter your password anyways. Username: rkh Password: ******************* Successfully logged in! As you can see above, it will ask you for your GitHub user name and password, but not send these to Travis CI. Instead, it will use them to create a GitHub API token, show the token to Travis, which then on its own checks if you really are who you say you are, and gives you an access token for the Travis API in return. The client will then delete the GitHub token again, just to be sure. But don't worry, all that happens under the hood and fully automatic. If you don't want it to send your credentials to GitHub, you can create a GitHub token on your own and supply it via `--github-token`. In that case, the client will not delete the GitHub token (as it can't, it needs your password to do this). Travis CI will not store the token, though - after all, it already should have a valid token for you in the database. A third option is for the really lazy: `--auto`. In this mode the client will try to find a GitHub token for you and just use that. This will only work if you have a [global GitHub token](https://help.github.com/articles/git-over-https-using-oauth-token) stored in your [.netrc](http://blogdown.io/c4d42f87-80dd-45d5-8927-4299cbdf261c/posts/574baa68-f663-4dcf-88b9-9d41310baf2f). If you haven't heard of this, it's worth looking into in general. Again: Travis CI will not store that token. #### `raw` This is really helpful both when working on this client and when exploring the [Travis API](https://api.travis-ci.org). It will simply fire a request against the API endpoint, parse the output and pretty print it. Keep in mind that the client takes care of authentication for you: $ travis raw /repos/travis-ci/travis {"repo"=> {"id"=>409371, "slug"=>"travis-ci/travis", "description"=>"Travis CI Client (CLI and Ruby library)", "last_build_id"=>4251410, "last_build_number"=>"77", "last_build_state"=>"passed", "last_build_duration"=>351, "last_build_language"=>nil, "last_build_started_at"=>"2013-01-19T18:00:49Z", "last_build_finished_at"=>"2013-01-19T18:02:17Z"}} Use `--json` if you'd rather prefer the output to be JSON. ### `sync` Usage: travis sync [options] -h, --help Display help -i, --[no-]interactive be interactive and colorful -E, --[no-]explode don't rescue exceptions -e, --api-endpoint URL Travis API server to talk to --pro short-cut for --api-endpoint 'https://api.travis-ci.com/' --org short-cut for --api-endpoint 'https://api.travis-ci.org/' -t, --token [ACCESS_TOKEN] access token to use --debug show API requests -c, --check only check the sync status -b, --background will trigger sync but not block until sync is done -f, --force will force sync, even if one is already running Sometimes the infos Travis CI has about users and repositories become out of date. If that should happen, you can manually trigger a sync: $ travis sync synchronizing: ........... done The command blocks until the synchronization is done. You can avoid that with `--background`: $ travis sync --background starting synchronization If you just want to know if your account is being synchronized right now, use `--check`: $ travis sync --check rkh is currently syncing #### `token` In order to use the Ruby library you will need to obtain an access token first. To do this simply run the `travis login` command. Once logged in you can check your token with `travis token`: $ travis token Your access token is super-secret You can use that token for instance with curl: $ curl -H "Authorization: token $(travis token)" https://api.travis-ci.org/users/ {"login":"rkh","name":"Konstantin Haase","email":"konstantin.haase@gmail.com","gravatar_id":"5c2b452f6eea4a6d84c105ebd971d2a4","locale":"en","is_syncing":false,"synced_at":"2013-01-21T20:31:06Z"} Note that if you just need it for looking at API payloads, that we also have the [`raw`](#raw) command. #### `whatsup` It's just a tiny feature, but it allows you to take a look at repositories that have recently seen some action (ie the left hand sidebar on [travis-ci.org](https://travis-ci.org)): $ travis whatsup mysociety/fixmystreet started: #154 eloquent/typhoon started: #228 Pajk/apipie-rails started: #84 qcubed/framework failed: #21 ... #### `whoami` This command is useful to verify that you're in fact logged in: $ travis whoami You are rkh (Konstantin Haase) Again, like most other commands, goes well with shell scripting: $ git clone "https://github.com/$(travis whoami)/some_project" ### Repository Commands -h, --help Display help -i, --[no-]interactive be interactive and colorful -E, --[no-]explode don't rescue exceptions -e, --api-endpoint URL Travis API server to talk to --pro short-cut for --api-endpoint 'https://api.travis-ci.com/' --org short-cut for --api-endpoint 'https://api.travis-ci.org/' -t, --token [ACCESS_TOKEN] access token to use --debug show API requests -r, --repo SLUG Repository commands have all the options [General API Commands](#general-api-commands) have. Additionally, you can specify the Repository to talk to by providing `--repo owner/name`. However, if you invoke the command inside a clone of the project, the client will figure out this option on its own. Note that it uses the [git remote](http://www.kernel.org/pub/software/scm/git/docs/git-remote.html) "origin" to do so. It will also automatically pick [Travis Pro](https://travis-ci.com) if it is a private project. You can of course override this decission with `--pro`, `--org` or `--api-endpoint URL` #### `disable` If you want to turn of a repository temporarily or indefinitely, you can do so with the `disable` command: $ travis disable travis-ci/travis: disabled :( #### `enable` With the `enable` command, you can easily activate a project on Travis CI: $ travis enable travis-ci/travis: enabled :) It even works when enabling a repo Travis didn't know existed by triggering a sync: $ travis enable -r rkh/test repository not known to Travis CI (or no access?) triggering sync: ............. done rkh/test: enabled If you don't want the sync to be triggered, use `--skip-sync`. #### `encrypt` Usage: travis encrypt [args..] [options] -h, --help Display help -i, --[no-]interactive be interactive and colorful -E, --[no-]explode don't rescue exceptions -e, --api-endpoint URL Travis API server to talk to --pro short-cut for --api-endpoint 'https://api.travis-ci.com/' --org short-cut for --api-endpoint 'https://api.travis-ci.org/' -t, --token [ACCESS_TOKEN] access token to use --debug show API requests -r, --repo SLUG --add [KEY] adds it to .travis.yml under KEY (default: env.global) -s, --[no-]split treat each line as a separate input This command is useful to encrypt [environment variables](http://about.travis-ci.org/docs/user/encryption-keys/) or deploy keys for private dependencies. $ travis encrypt FOO=bar Please add the following to your .travis.yml file: secure: "gSly+Kvzd5uSul15CVaEV91ALwsGSU7yJLHSK0vk+oqjmLm0jp05iiKfs08j\n/Wo0DG8l4O9WT0mCEnMoMBwX4GiK4mUmGdKt0R2/2IAea+M44kBoKsiRM7R3\n+62xEl0q9Wzt8Aw3GCDY4XnoCyirO49DpCH6a9JEAfILY/n6qF8=" Pro Tip™: You can add it automatically by running with --add. For deploy keys, it is really handy to pipe them into the command: $ cat id_rsa | travis encrypt Another use case for piping files into it: If you have a file with sensitive environment variables, like foreman's [.env](http://ddollar.github.com/foreman/#ENVIRONMENT) file, you can add tell the client to encrypt every line separately via `--split`: $ cat .env | travis encrypt --split Please add the following to your .travis.yml file: secure: "KmMdcwTWGubXVRu93/lY1NtyHxrjHK4TzCfemgwjsYzPcZuPmEA+pz+umQBN\n1ZhzUHZwDNsDd2VnBgYq27ZdcS2cRvtyI/IFuM/xJoRi0jpdTn/KsXR47zeE\nr2bFxRqrdY0fERVHSMkBiBrN/KV5T70js4Y6FydsWaQgXCg+WEU=" secure: "jAglFtDjncy4E3upL/RF0ZOcmJ2UMrqHFCLQwU8PBdurhTMBeTw+IO6cXx5z\nU5zqvPYo/ghZ8mMuUhvHiGDM6m6OlMP7+l10VTxH1CoVew2NcQvRdfK3P+4S\nZJ43Hyh/ZLCjft+JK0tBwoa3VbH2+ZTzkRZQjdg54bE16C7Mf1A=" Pro Tip™: You can add it automatically by running with --add. As suggested, the client can also add them to your `.travis.yml` for you: $ travis encrypt FOO=bar --add This will by default add it as global variables for every job. You can also add it as matrix entries by providing a key: $ travis encrypt FOO=bar --add env.matrix #### `history` Usage: travis history [options] -h, --help Display help -i, --[no-]interactive be interactive and colorful -E, --[no-]explode don't rescue exceptions -e, --api-endpoint URL Travis API server to talk to --pro short-cut for --api-endpoint 'https://api.travis-ci.com/' --org short-cut for --api-endpoint 'https://api.travis-ci.org/' -t, --token [ACCESS_TOKEN] access token to use --debug show API requests -r, --repo SLUG -a, --after BUILD Only show history after a given build number -p, --pull-request NUMBER Only show history for the given Pull Request -b, --branch BRANCH Only show history for the given branch -l, --limit LIMIT Maximum number of history items --[no-]all Display all history items You can check out what the recent builds look like: $ travis history #77 passed: master fix name clash #76 failed: master Merge pull request #11 from travis-ci/rkh-show-logs-history #75 passed: rkh-debug what? #74 passed: rkh-debug all tests pass locally and on the travis vm I spin up :( #73 failed: Pull Request #11 regenerate gemspec #72 passed: rkh-show-logs-history regenerate gemspec #71 failed: Pull Request #11 spec fix for (older) rubinius #70 passed: rkh-show-logs-history spec fix for (older) rubinius #69 failed: Pull Request #11 strange fix for rubinius #68 failed: rkh-show-logs-history strange fix for rubinius By default, it will display the last 10 builds. You can limit (or extend) the number of builds with `--limit`: $ travis history --limit 2 #77 passed: master fix name clash #76 failed: master Merge pull request #11 from travis-ci/rkh-show-logs-history You can use `--after` to display builds after a certain build number (or, well, before, but it's called after to use the same phrases as the API): $ travis history --limit 2 --after 76 #75 passed: rkh-debug what? #74 passed: rkh-debug all tests pass locally and on the travis vm I spin up :( You can also limit the history to builds for a certain branch: $ travis history --limit 3 --branch master #77 passed: master fix name clash #76 failed: master Merge pull request #11 from travis-ci/rkh-show-logs-history #57 passed: master Merge pull request #5 from travis-ci/hh-multiline-encrypt Or a certain Pull Request: $ travis history --limit 3 --pull-request 5 #56 passed: Pull Request #5 Merge branch 'master' into hh-multiline-encrypt #49 passed: Pull Request #5 improve output #48 passed: Pull Request #5 let it generate accessor for line splitting automatically #### `logs` Given a job number, logs simply prints out that job's logs. $ travis logs 77.1 [... more logs ...] Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed. $ bundle exec rake /home/travis/.rvm/rubies/ruby-1.8.7-p371/bin/ruby -S rspec spec -c Faraday: you may want to install system_timer for reliable timeouts ................................................................................................................................................................... Finished in 6.48 seconds 163 examples, 0 failures Done. Build script exited with: 0 #### `open` Opens the project view in the Travis CI web interface. If you pass it a build or job number, it will open that specific view: $ travis open If you just want the URL printed out instead of opened in a browser, pass `--print`. If instead you want to open the repository, compare or pull request view on GitHub, use `--github`. $ travis open 56 --print --github web view: https://github.com/travis-ci/travis/pull/5 #### `restart` This command will restart the latest build: $ travis restart build #85 has been restarted You can also restart any build by giving a build number: $ travis restart 57 build #57 has been restarted Or a single job: $ travis restart 57.1 job #57.1 has been restarted #### `show` Displays general infos about the latest build: $ travis show Build #77: fix name clash State: passed Type: push Compare URL: https://github.com/travis-ci/travis/compare/7cc9b739b0b6...39b66ee24abe Duration: 5 min 51 sec Started: 2013-01-19 19:00:49 Finished: 2013-01-19 19:02:17 #77.1 passed: 45 sec rvm: 1.8.7 #77.2 passed: 50 sec rvm: 1.9.2 #77.3 passed: 45 sec rvm: 1.9.3 #77.4 passed: 46 sec rvm: 2.0.0 #77.5 failed: 1 min 18 sec rvm: jruby (failure allowed) #77.6 passed: 1 min 27 sec rvm: rbx Any other build: $ travis show 1 Build #1: add .travis.yml State: failed Type: push Compare URL: https://github.com/travis-ci/travis/compare/ad817bc37c76...b8c5d3b463e2 Duration: 3 min 16 sec Started: 2013-01-13 23:15:22 Finished: 2013-01-13 23:21:38 #1.1 failed: 21 sec rvm: 1.8.7 #1.2 failed: 34 sec rvm: 1.9.2 #1.3 failed: 24 sec rvm: 1.9.3 #1.4 failed: 52 sec rvm: 2.0.0 #1.5 failed: 38 sec rvm: jruby #1.6 failed: 27 sec rvm: rbx Or a job: $ travis show 77.3 Job #77.3: fix name clash State: passed Type: push Compare URL: https://github.com/travis-ci/travis/compare/7cc9b739b0b6...39b66ee24abe Duration: 45 sec Started: 2013-01-19 19:00:49 Finished: 2013-01-19 19:01:34 Allow Failure: false Config: rvm: 1.9.3 #### `status` Usage: travis status [options] -h, --help Display help -i, --[no-]interactive be interactive and colorful -E, --[no-]explode don't rescue exceptions -e, --api-endpoint URL Travis API server to talk to --pro short-cut for --api-endpoint 'https://api.travis-ci.com/' --org short-cut for --api-endpoint 'https://api.travis-ci.org/' -t, --token [ACCESS_TOKEN] access token to use --debug show API requests -r, --repo SLUG -x, --[no-]exit-code sets the exit code to 1 if the build failed -q, --[no-]quiet does not print anything -p, --[no-]fail-pending sets the status code to 1 if the build is pending Outputs a one line status message about the project's last build. With `-q` that line will even not be printed out. How's that useful? Combine it with `-x` and the exit code will be 1 if the build failed, with `-p` and it will be 1 for a pending build. $ travis status -qpx && cap deploy ## Ruby Library There are two approaches of using the Ruby library, one straight forward with one global session: ``` ruby require 'travis' rails = Travis::Repository.find('rails/rails') puts "oh no" unless rails.green? ``` And one where you have to instantiate your own session: ``` ruby require 'travis/client' client = Travis::Client.new rails = client.repo('rails/rails') puts "oh no" unless rails.green? ``` For most parts, those are pretty much the same, the entities you get back look the same, etc, except one offers nice constants as part of the API, the other doesn't. In fact the "global" session style uses `Travis::Client` internally. So, which one to choose? The global style has one session, whereas with the client style, you have one session per client instance. Each session has it's own cache and identity map. This might matter for log running processes. If you use a new session for separate units of work, you can be pretty sure to not leak any objects. On the other hand using the constants or reusing the same session might save you from unnecessary HTTP requests. In either way, if you should use the first approach or long living clients, here is how you make sure not to have stale data around: ``` ruby Travis.clear_cache client.clear_cache ``` Note that this will still keep the identity map around, it will only drop all attributes. To clear the identity map, you can use the `clear_cache!` method. However, if you do that, you should not keep old instances of any entities (like repositories, etc) around. ### Authentication Authentication is pretty easy, you just need to set an access token: ``` ruby require 'travis' Travis.access_token = "..." puts "Hello #{Travis::User.current.name}!" ``` Or with your own client instance: ``` ruby require 'travis/client' client = Travis::Client.new puts "Hello #{client.user.name}" ``` See [the token command](#token) for obtaining the access token used by the CLI. If you don't have an access token for Travis CI, you can use a GitHub access token to get one: ``` ruby require 'travis' Travis.github_auth("...") puts "Hello #{Travis::User.current.name}!" ``` Travis CI will not store that token. ### Using Pro Using the library with private projects pretty much works the same, except you use `Travis::Pro`. Keep in mind that you need to authenticate. ``` ruby require 'travis/pro' Travis::Pro.access_token = '...' user = Travis::Pro::User.current puts "Hello #{user.name}!" ``` ### Entities Entities are like the models in the Travis Client land. They keep the data and it's usually them you talk to if you want something. They are pretty much normal Ruby objects. The Travis session will cache all entities, so don't worry about loading the same one twice. Once you got a hold of one, you can easily reload it at any time if you want to make sure the data is fresh: ``` ruby rails = Travis::Repository.find('rails/rails') sleep 1.hour rails.reload ``` The travis gem supports lazy and partial loading, so if you want to make sure you have all the data, just call load. ``` ruby rails.load ``` This is not something you should usually do, as partial loading is actually your friend (keeps requests to a minimum). #### Stateful Entities [Repositories](#repositories), [Builds](#builds) and [Jobs](#jobs) all are basically state machines, which means the implement the following methods: ``` ruby require 'travis' build = Travis::Repository.find('rails/rails').last_build p build.canceled? p build.created? p build.errored? p build.failed? p build.finished? p build.green? p build.passed? p build.pending? p build.queued? p build.red? p build.running? p build.started? p build.successful? p build.unsuccessful? p build.yellow? p build.color ``` Builds and jobs also have a `state` method. For repositories, use `last_build.state`. #### Repositories Repositories are probably one of the first entities you'll load. It's pretty straight forward, too. ``` ruby require 'travis' Travis::Repository.find('rails/rails') # find by slug Travis::Repository.find(891) # find by id Travis::Repository.find_all(owner_name: 'rails') # all repos in the rails organization Travis::Repository.current # repos that see some action right now ``` Once you have a repository, you can for instance encrypt some strings with its private key: ``` ruby require 'travis' Travis::Repository.find('rails/rails') puts repo.encrypt('FOO=bar') ``` Repositories are [stateful](#stateful-entities). You can enable or disable a repository with the methods that go by the same name. ``` ruby rails.disable system "push all the things" rails.enable ``` If you want to enable a new project, you might have to do a sync first. #### Builds You could load a build by its id using `Travis::Build.find`. But most of the time you won't have the id handy, so you'd usually start with a repository. ``` ruby require 'travis' rails = Travis::Repository.find('rails/rails') rails.last_build # the latest build rails.recent_builds # the last 20 or so builds (don't rely on that number) rails.builds(after_number: 42) # the last 20 or so builds *before* 42 rails.build(42) # build with the number 42 (not the id!) rails.builds # Enumerator for #each_build # this will loop through all builds rails.each_build do |build| puts "#{build.number}: #{build.state}" end # this will loop through all builds before build 42 rails.each_build(after_number: 42) do |build| puts "#{build.number}: #{build.state}" end ``` Note that `each_build` (and thus `builds` without and argument) is lazy and uses pagination, so you can safely do things like this: ``` ruby build = rails.builds.detect { |b| b.failed? } puts "Last failing Rails build: #{build.number}" ``` Without having to load more than 6000 builds. You can restart a build, if the current user has sufficient permissions on the repository: ``` ruby rails.last_build.restart ``` #### Jobs Jobs behave a lot like [builds](#builds), and similar to them, you probably don't have the id ready. You can get the jobs from a build: ``` ruby rails.last_build.jobs.each do |job| puts "#{job.number} took #{job.duration} seconds" end ``` If you have the job number, you can also reach a job directly from the repository: ``` ruby rails.job('5000.1') ``` Like builds, you can also restart singe jobs: ``` ruby rails.job('5000.1').restart ``` #### Artifacts The artifacts you usually care for are probably logs. You can reach them directly from a build: ``` ruby require 'travis' repo = Travis::Repository.find('travis-ci/travis') job = repo.last_build.jobs.first puts job.log.body ``` If you plan to print our the body, be aware that it might contain malicious escape codes. For this reason, we added `colorized_body`, which removes all the unprintable characters, except for ANSI color codes, and `clean_body` which also removes the color codes. ``` ruby puts job.log.colorized_body ```` #### Users The only user you usually get access to is the currently authenticated one. ``` ruby require 'travis' Travis.access_token = '...' user = Travis::User.current puts "Hello, #{user.login}! Or should I call you... #{user.name.upcase}!?" ``` If some data gets out of sync between GitHub and Travis, you can use the user object to trigger a new sync. ``` ruby Travis::User.current.sync ``` #### Commits Commits cannot be loaded directly. They come as a byproduct of [jobs](#jobs) and [builds](#builds). ``` ruby require 'travis' repo = Travis::Repository.find('travis-ci/travis') commit = repo.last_build.commit puts "Last tested commit: #{commit.short_sha} on #{commit.branch} by #{commit.author_name} - #{commit.subject}" ``` #### Workers If a worker is running something, it will reference a `job` and a `repository`. Otherwise the values will be `nil`. ``` ruby require 'travis' workers = Travis::Worker.find_all workers.each do |worker| puts "#{worker.name}: #{worker.host} - #{worker.state} - #{worker.repository.slug if worker.repository}" end ``` ### Dealing with Sessions Under the hood the session is where the fun is happening. Most methods on the constants and entities just wrap methods on your session, so you don't have to pass the session around all the time or even see it if you don't want to. There are two levels of session methods, the higher level methods from the `Travis::Client::Methods` mixin, which are also available from `Travis`, `Travis::Pro` or any custom [Namespace](#using-namespaces). ``` ruby require 'travis/client/session' session = Travis::Client::Session.new session.access_token = "secret_token" # access token to use session.api_endpoint = "http://localhost:3000/" # api endpoint to talk to session.github_auth("github_token") # log in with a github token session.repos(owner_name: 'travis-ci') # all travis-ci/* projects session.repo('travis-ci/travis') # this project session.repo(409371) # same as the one above session.build(4266036) # build with id 4266036 session.job(4266037) # job with id 4266037 session.artifact(42) # artifact with id 42 session.log(42) # same as above session.user # the current user, if logged in session.restart(session.build(4266036)) # restart some build ``` You can add these methods to any object responding to `session` via said mixin. Below this, there is a second API, close to the HTTP level: ``` ruby require 'travis/client/session' session = Travis::Client::Session.new session.instrument do |description, block| time = Time.now block.call puts "#{description} took #{Time.now - time} seconds" end session.connection = Faraday::Connection.new session.get_raw('/repos/rails/rails') # => {"repo" => {"id" => 891, "slug" => "rails/rails", ...}} session.get('/repos/rails/rails') # => {"repo" => #} session.headers['Foo'] = 'Bar' # send a custom HTTP header with every request rails = session.find_one(Travis::Client::Repository, 'rails/rails') session.find_many(Travis::Client::Repository) # repositories with the latest builds session.find_one_or_many(Travis::Client::User) # the current user (you could also use find_one here) session.reload(rails) session.reset(rails) # lazy reload session.clear_cache # empty cached attributes session.clear_cache! # empty identity map ``` ### Using Namespaces `Travis` and `Travis::Pro` are just two different namespaces for two different Travis sessions. A namespace is a Module, exposing the higher level [session methods](#dealing-with-sessions). It also has a dummy constant for every [entity](#entities), wrapping `find_one` (aliased to `find`) and `find_many` (aliased to `find_all`) for you, so you don't have to keep track of the session or hand in the entity class. You can easily create your own namespace: ``` ruby require 'travis/client' MyTravis = Travis::Client::Namespaces.new("http://localhost:3000") MyTravis.access_token = "..." MyTravis::Repository.find("foo/bar") ``` Since namespaces are Modules, you can also include them. ``` ruby require 'travis/client' class MyTravis include Travis::Client::Namespaces.new end MyTravis::Repository.find('rails/rails') ``` ## Installation Make sure you have at least [Ruby](http://www.ruby-lang.org/en/downloads/) 1.8.7 (1.9.3 recommended) installed. Then run: $ gem install travis --no-rdoc --no-ri ### Upgrading from travis-cli If you have the old `travis-cli` gem installed, you should `gem uninstall travis-cli`, just to be sure, as it ships with an executable that is also named `travis`. ## Version History **v1.2.1** (May 24, 2013) * Builds with high build numbers are properly aligned when running `travis history`. * Don't lock against a specific backports version, makes it easier to use it as a Ruby library. * Fix encoding issues. **v1.2.0** (February 22, 2013) * add `--adapter` to API endpoints * added branch to `show` * fix bug where colors were not used if stdin is a pipe * make `encrypt` options `--split` and `--add` work together properly * better handling of missing or empty `.travis.yml` when running `encrypt --add` * fix broken example code * no longer require network connection to automatically detect repository slug * add worker support to the ruby library * adjust artifacts/logs code to upstream api changes **v1.1.3** (January 26, 2013) * use persistent HTTP connections (performance for commands with multiple api requests) * include round trip time in debug output **v1.1.2** (January 24, 2013) * `token` command * no longer wrap $stdin in delegator (caused bug on some Linux systems) * correctly detect when running on Windows, even on JRuby **v1.1.1** (January 22, 2013) * Make pry a runtime dependency rather than a development dependency. **v1.1.0** (January 21, 2013) * New commands: `console`, `status`, `show`, `logs`, `history`, `restart`, `sync`, `enable`, `disable`, `open` and `whatsup`. * `--debug` option for all API commands. * `--split` option for `encrypt`. * Fix `--add` option for `encrypt` (was naming key `secret` instead of `secure`). * First class representation for builds, commits and jobs in the Ruby library. * Print warning when running "encrypt owner/project data", as it's not supported by the new client. * Improved documentation. **v1.0.3** (January 15, 2013) * Fix `-r slug` for repository commands. (#3) **v1.0.2** (January 14, 2013) * Only bundle CA certs needed to verify Travis CI and GitHub domains. * Make tests pass on Windows. **v1.0.1** (January 14, 2013) * Improve `encrypt --add` behavior. **v1.0.0** (January 14, 2013) * Fist public release. * Improved documentation. **v1.0.0pre2** (January 14, 2013) * Added Windows support. * Suggestion to run `travis login` will add `--org` if needed. **v1.0.0pre** (January 13, 2013) * Initial public prerelease.