{"id":19736810,"url":"https://github.com/travis-ci/travis-ruby-client","last_synced_at":"2025-04-30T04:32:20.058Z","repository":{"id":59157994,"uuid":"2174801","full_name":"travis-ci/travis-ruby-client","owner":"travis-ci","description":"Ruby client library for Travis CI API","archived":false,"fork":false,"pushed_at":"2020-09-08T20:46:47.000Z","size":207,"stargazers_count":19,"open_issues_count":1,"forks_count":10,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-05T22:32:10.515Z","etag":null,"topics":["api-client","ruby","travis-ci"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/travis-ci.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-08-08T17:31:10.000Z","updated_at":"2022-09-28T23:10:44.000Z","dependencies_parsed_at":"2022-09-13T20:10:14.381Z","dependency_job_id":null,"html_url":"https://github.com/travis-ci/travis-ruby-client","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travis-ci%2Ftravis-ruby-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travis-ci%2Ftravis-ruby-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travis-ci%2Ftravis-ruby-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travis-ci%2Ftravis-ruby-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/travis-ci","download_url":"https://codeload.github.com/travis-ci/travis-ruby-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251643266,"owners_count":21620461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","ruby","travis-ci"],"created_at":"2024-11-12T01:08:36.528Z","updated_at":"2025-04-30T04:32:19.790Z","avatar_url":"https://github.com/travis-ci.png","language":"Ruby","readme":"# Travis CI API Client\n\nRuby client for the [Travis CI API, version 3](https://developer.travis-ci.com/).\n\n## Installation\n\nYou can install it as a RubyGem via:\n\n``` console\n$ gem install travis-client\n```\n\nNote that it does conflict with [travis.rb](https://github.com/travis-ci/travis.rb) at the moment, as both of them add a `travis/client` file. It is highly recommended to use [Bundler](http://bundler.io/) to avoid accidentally loading the wrong gem in your scripts.\n\n## Getting Started\n\nThis library has two general ways to use it. An interface based on globals, that should feel quite natural to Ruby developers:\n\n``` ruby\nrequire 'travis/client'\nTravis.connect # call before interacting with anything else\nrepository = Travis::Repository.find(slug: 'travis-ci/travis-web')\n```\n\nOr 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:\n\n``` ruby\nrequire 'travis/client'\nconnection = Travis.new\nsession    = connection.create_session\nrepository = session.find_repository(slug: 'travis-ci/travis-web')\n```\n\nObjects returned by `Repository.find` and `find_repository` are identical. You can access the underlying session object used by `Travis::Repository.find` via `Travis.session`.\n\nEach session will have its own cache, and HTTP connections. Recreating connection objects (by either calling `Travis.connect` or `Travis.new`) frequently should be avoided, as it will rebuild internal factories based on the API auto-discovery.\n\nBoth `Travis.new` and `Travis.connect` accept the following options:\n\n* **endpoint:** URI for the entry point to the Travis CI API, defaults to `https://api.travis-ci.org`. Set this to `https://api.travis-ci.com` for the Pro version of Travis CI, `https://travis.your-domain.com/api`  for Travis CI Enterprise (assuming your Enterprise web UI is reachable under `https://travis.your-domain.com`).\n* **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`.\n* **access_token:** API access token to use for authentication.\n\n## Advanced Features\n\n### Authentication\n\nYou'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 [travis-ci.org](https://developer.travis-ci.org/explore/user) and [travis-ci.com](https://developer.travis-ci.com/explore/user), and you will have to use the appropriate token depending on which API you interact with.\n\nAlternatively, you can use the [`token` command](https://github.com/travis-ci/travis.rb#token) from the CLI.\n\n``` ruby\n# connecting to travis-ci.org with a token stored in TRAVIS_TOKEN env var\nTravis.connect(access_token: ENV['TRAVIS_TOKEN'])\n\n# connecting to travis-ci.com with a token stored in TRAVIS_PRO_TOKEN env var\nTravis.connect(api_endpoint: 'https://api.travis-ci.com' access_token: ENV['TRAVIS_PRO_TOKEN'])\n```\n\nWhen 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:\n\n``` ruby\nconnection = Travis.new(access_token: ENV['TRAVIS_TOKEN'])\nputs connection.create_session.current_user.login\n\n\n# for a list of tokens, output which user is associated with it\naccess_tokens = [ ... list of tokens ... ]\nconnection    = Travis.new(api_endpoint: 'https://api.travis-ci.com')\naccess_tokens.each do |token|\n  session     = connection.create_session(access_token: token)\n  puts session.current_user.login\nend\n```\n\n### Caching and Session Renewal\n\nEach 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.\n\nIn 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).\n\n``` ruby\nrequire 'sinatra'\nrequire 'travis/client'\n\n# create connection once, but create one session per request\nconnection = Travis.new(access_token: ENV['TRAVIS_TOKEN'])\nbefore { @travis = connection.create_session }\n\nget '/' do\n  \"Hello, #{@travis.current_user.name}!\"\nend\n```\n\nIf 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.\n\n### Thread Safety\n\nNeither `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.\n\nTo use with a threaded environment:\n\n* Initialize a new connection once, via `Travis.new`.\n* From this connection, create one session per thread via `#create_session`.\n\nExample that fetches repositories in parallel:\n\n``` ruby\nrequire 'travis/client'\n\nrepositories = ['travis-ci/travis-web', 'travis-ci/travis-api', 'sinatra/sinatra']\nconnection   = Travis.new\nthreads      = repositories.map do |slug|\n  Thread.new { connection.create_session.find_repository(slug: slug) }\nend\n\nthreads.each do |thread|\n  puts thread.value.name\nend\n```\n\n### Permission Checks\n\nYou can check permissions on any entity object via the `permission?` method:\n\n``` ruby\nTravis::User.current.permission? :sync                    # =\u003e true\nTravis::Owner.find(login: 'svenfuchs').permission? :sync  # =\u003e false\n\nuser = Travis::User.current\nuser.sync if user.permission? :sync\n```\n\nYou can find a full list of permission in the [developer documentation](https://developer.travis-ci.org/).\n\n### Eager Loading\n\nThe following code will trigger two HTTP requests, one to fetch the repository, and one to fetch the last build on the default branch:\n\n``` ruby\nrepository = Travis::Repository.find(slug: 'travis-ci/travis-api')\nputs repository.default_branch.last_build.state\n```\n\nYou can reduce this to a single HTTP request by eager loading `branch.last_build`:\n\n``` ruby\nrepository = Travis::Repository.find(slug: 'travis-ci/travis-api', include: 'branch.last_build')\nputs repository.default_branch.last_build.state\n```\n\n### Pagination\n\nEach object representing a collection is an Enumerable and will handle pagination in a transparent way:\n\n``` ruby\n# will automatically paginate if necessary\nrepository.branches.map { |branch| branch.name }\n```\n\nJust 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.\n\nYou can also use the `limit`, `offset` and `sort` parameters to fine-tune requests.\n\n### Request Hooks and Instrumentation\n\nYou can add hooks that will trigger before or after any HTTP request:\n\n``` ruby\nTravis.before_request { |r| puts \"** #{r.request_method} #{r.uri}\"}\nTravis::Repository.find(slug: 'rails/rails')\n```\n\nYou can use the `meta_data` hash to share data between hooks:\n\n``` ruby\nTravis.before_request do |request|\n  request.meta_data[:start] = Time.now\nend\n\nTravis.after_request do |request|\n  duration = Time.now - request.meta_data[:start]\n  puts \"** #{request.request_method} #{request.uri} - #{request.response.status} - #{duration}s\"\nend\n\nTravis::Repository.find(slug: 'rails/rails')\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravis-ci%2Ftravis-ruby-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftravis-ci%2Ftravis-ruby-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravis-ci%2Ftravis-ruby-client/lists"}