Logo

© 2024 Travis CI GmbH
Rigaerstr. 8,
10247 柏林，德国

概述

API V3

我们最新的 API 是 V3，它有自己的 API 资源管理器。如果您是 Travis CI API 的新手，您应该使用 API V3。

本页面介绍的 API V2 将在 2018 年的某个时间点被弃用。

API V2.1

API V2.1 与 API V2 相同，但以下更改除外

V2 的先前行为是这些请求会收到 401 错误。

类似的 HTTP 响应代码模式适用于其他端点，例如 /builds、/branches、/jobs 和 /requests。

要使用 API V2.1，请将 API 请求的 Accept 标头设置为 application/vnd.travis-ci.2.1+json。

发出请求

GET / HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Host: api.travis-ci.org

GET / HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token "YOUR TRAVIS ACCESS TOKEN"
Host: api.travis-ci.com

GET /api HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token "YOUR TRAVIS ACCESS TOKEN"
Host: travis.example.com

$ travis raw /
{"hello"=>"world"}

$ travis raw / --com
{"hello"=>"world"}

$ travis raw / --api-endpoint https://travis.example.com/api
{"hello"=>"world"}

require 'travis'

# talk to travis-ci.org via client object
client = Travis::Client.new
repository = client.repo('travis-ci/travis.rb')

# talk to travis-ci.org via Travis namespace
repository = Travis::Repository.find('travis-ci/travis.rb')

# talk to travis-ci.com via client object
client = Travis::Client.new('https://api.travis-ci.com')
client.access_token = 'YOUR TRAVIS ACCESS TOKEN'
repository = client.repo('travis-pro/billing')

# talk to travis-ci.com via Travis::Pro namespace
Travis::Pro.access_token = 'YOUR TRAVIS ACCESS TOKEN'
repository = Travis::Pro::Repository.find('travis-pro/billing')

# talk to travis.example.com via client object
client = Travis::Client.new('https://travis.example.com/api')
client.access_token = 'YOUR TRAVIS ACCESS TOKEN'
repository = client.repo('my/repo')

# talk to travis.example.com via custom namespace
My = Travis::Client::Namespaces.new('https://travis.example.com/api')
My.access_token = 'YOUR TRAVIS ACCESS TOKEN'
My::Repository.find('my/repo')

您需要首先了解要使用哪个 API URL 端点

当您编写自己的 Travis CI 客户端时，请牢记以下几点

客户端库通常会自动设置这些标头。

外部 API

GET /config HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "config": {
    "host": "travis-ci.org",
    "pusher": { "key": "5df8ac576dcccf4fd076" },
    "github": {
      "api_url": "https://api.github.com",
      "scopes": [
        "read:org", "user:email", "repo_deployment",
        "repo:status", "write:repo_hook"
      ]
    }
  }
}

$ travis raw /config
{"config"=>
  {"host"=>"travis-ci.org",
   "pusher"=>{"key"=>"5df8ac576dcccf4fd076"},
   "github"=>
    {"api_url"=>"https://api.github.com",
     "scopes"=>
      ["read:org",
       "user:email",
       "repo_deployment",
       "repo:status",
       "write:repo_hook"]}}}

require 'travis'
client = Travis::Client.new
client.config
# => {"host"=>"travis-ci.org",
#     "pusher"=>{"key"=>"5df8ac576dcccf4fd076"},
#     "github"=>
#      {"api_url"=>"https://api.github.com",
#       "scopes"=>
#        ["read:org",
#         "user:email",
#         "repo_deployment",
#         "repo:status",
#         "write:repo_hook"]}}

Travis CI 与外部服务集成，您的客户端库可能希望直接与其中一些服务进行交互。最重要的是，它使用 GitHub 作为用户、组织和存储库的来源，并使用 Pusher 来实时流式传输日志。

您可以通过加载 config 端点来向 API 请求与这些服务的连接详细信息。

这包括以下内容，除此之外还有其他内容

身份验证

GET /users HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Host: api.travis-ci.org
Authorization: token "YOUR TRAVIS ACCESS TOKEN"

$ travis whoami -t "YOUR TRAVIS ACCESS TOKEN"

require 'travis'

# against the Travis namespace
Travis.access_token = 'YOUR TRAVIS ACCESS TOKEN'
Travis::User.current

# against a client object
client = Travis::Client.new(access_token: 'YOUR TRAVIS ACCESS TOKEN')
client.user

要对 Travis CI 进行身份验证，您需要一个 API 访问令牌。

您可以使用 GitHub 令牌来证明您的身份，从而检索令牌。将来，我们计划为第三方应用程序添加适当的 OAuth 握手。

您也可以从 Travis CI 个人资料页面获取 API 令牌，用于 公共存储库 或 私有存储库。

使用 GitHub 令牌

POST /auth/github HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Host: api.travis-ci.org
Content-Type: application/json
Content-Length: 37

{"github_token":"YOUR GITHUB TOKEN"}

HTTP/1.1 200 OK
Content-Type: application/json

{"access_token":"YOUR TRAVIS ACCESS TOKEN"}

$ travis login --github-token "YOUR GITHUB TOKEN"
Successfully logged in!

$ travis token
Your access token is YOUR TRAVIS ACCESS TOKEN

require 'travis'

# against the Travis namespace
Travis.github_auth(token)

# against a client object
client = Travis::Client.new
client.github_auth(token)

如果您有 GitHub 令牌，您可以使用 GitHub 身份验证端点将其交换为访问令牌。Travis API 服务器不会存储该令牌，也不会将其用于除验证用户帐户以外的任何其他用途。

因此请注意，API 不能用于创建新用户帐户。用户必须至少通过 Web 界面登录一次，然后才能通过其他方式与 API 交互。

创建临时 GitHub 令牌

POST /authorizations HTTP/1.1
Host: api.github.com
Content-Type: application/json
Authorization: Basic ...

{
  "scopes": [
    "read:org", "user:email", "repo_deployment",
    "repo:status", "write:repo_hook"
  ],
  "note": "temporary token to auth against travis"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "read:org", "user:email", "repo_deployment",
    "repo:status", "write:repo_hook"
  ],
  "token": "YOUR GITHUB TOKEN",
  "note": "temporary token to auth against travis"
}

POST /auth/github HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Host: api.travis-ci.org
Content-Type: application/json
Content-Length: 37

{"github_token":"YOUR GITHUB TOKEN"}

HTTP/1.1 200 OK
Content-Type: application/json

{"access_token":"YOUR TRAVIS ACCESS TOKEN"}

DELETE /authorizations/1 HTTP/1.1
Host: api.github.com
Authorization: Basic ...

$ travis login --auto
Successfully logged in!

$ travis token
Your access token is YOUR TRAVIS ACCESS TOKEN

require 'travis'
require 'travis/tools/github'

# drop_token will make the token a temporary one
github = Travis::Tools::Github.new(drop_token: true) do |g|
  g.ask_login    = -> { print("GitHub login:     "); gets }
  g.ask_password = -> { print("Password:         "); gets }
  g.ask_otp      = -> { print("Two-factor token: "); gets }
end

github.with_token do |token|
  Travis.github_auth(token)
end

Travis.access_token # => "YOUR TRAVIS ACCESS TOKEN"

由于 Travis CI 不会存储用于身份验证的 GitHub 令牌，因此可以生成一个临时 GitHub 令牌，并在身份验证握手后将其删除。

要创建和删除 GitHub 令牌，您可以使用 GitHub Web 界面，也可以通过 GitHub API 自动执行此操作。

确保您的 GitHub 令牌具有 Travis CI 所需 的范围。

如果您自动执行此过程，身份验证将成为由三个请求组成的握手

一些客户端库会为您自动执行此握手。

GitHub OAuth 握手

触发 GitHub 和 Travis CI 之间的 OAuth 握手

<a href="https://api.travis-ci.com/auth/handshake">log in</a>

在 iframe 中运行 OAuth 握手

<script>
  window.addEventListener("message", function(event) {
    console.log("received token: " + event.data.token);
  });

  var iframe = $('<iframe />').hide();
  iframe.appendTo('body');
  iframe.attr('src', "https://api.travis-ci.org/auth/post_message");
</script>

您也可以通过在 Web 浏览器中打开 /auth/handshake 来触发 Travis CI 和 GitHub 之间的完整 OAuth 握手。该端点接受一个可选的 redirect_uri 查询参数，该参数将接收一个 URL，如果握手成功，Web 浏览器将最终到达该 URL。

还有一个替代版本，它将尝试在隐藏的 iframe 中运行握手，并使用 window.postMessage 将令牌传递给嵌入 iframe 的网站。此端点仅适用于白名单网站。

实体

帐户

GET /accounts HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Host: api.travis-ci.org
Authorization: token "YOUR TRAVIS ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
   "accounts" : [
      {
         "repos_count" : 167,
         "name" : "Konstantin Haase",
         "type" : "user",
         "id" : 267,
         "login" : "rkh"
      },
      {
         "repos_count" : 70,
         "name" : "Travis CI",
         "type" : "organization",
         "id" : 87,
         "login" : "travis-ci"
      }
   ]
}

$ travis accounts
rkh (Konstantin Haase): subscribed, 167 repositories
travis-ci (Travis CI): subscribed, 70 repositories

require 'travis'
Travis.access_token = 'YOUR TRAVIS ACCESS TOKEN'

Travis.accounts.each do |account|
  puts "#{account.login} has #{account.repos_count}"
end

用户可能有多个帐户。这通常是直接对应于用户的帐户，以及每个 GitHub 组织一个帐户。

属性

属性 描述
id 用户或组织 ID
name GitHub 上的帐户名称
login GitHub 上的帐户登录名
type user 或 organization
repos_count 存储库数量
subscribed 帐户是否具有有效订阅

subscribed 属性仅在 Travis Pro 上可用。

列出帐户

GET /accounts

参数 默认值 描述
all false 是否包含用户没有管理员访问权限的帐户

此请求始终需要进行身份验证。

分支

GET /repos/rails/rails/branches HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "branches": [
    {
      "id": 22554234,
      "repository_id": 891,
      "commit_id": 6534402,
      "number": "15184",
      "config": {},
      "state": "created",
      "started_at": "2014-04-08T00:17:34Z",
      "finished_at": "2014-04-08T00:48:59Z",
      "duration": 30546,
      "job_ids": [],
      "pull_request": false
    }
  ]
}

$ travis branches -r rails/rails
v4.1.0:         #15184 created  Dont encourage aliases now that …
master:         #15183 created  Dont abbreviate that which needs…
4-1-0:          #15183 created  Dont encourage aliases now that …
4-1-stable:     #15185 created  Merge branch '4-1-0' into 4-1-st…
adequaterecord: #15158 passed   wrap the literal value before ha…

require 'travis'

repository = Travis::Repository.find('rails/rails')
repository.branches
# => {"v4.1.0"          => #<Travis::Client::Build: rails/rails#15184>,
#      "master"         => #<Travis::Client::Build: rails/rails#15183>,
#      "4-1-0"          => #<Travis::Client::Build: rails/rails#15183>,
#      "4-1-stable"     => #<Travis::Client::Build: rails/rails#15185>,
#      "adequaterecord" => #<Travis::Client::Build: rails/rails#15158>,
#      "4-0-stable"     => #<Travis::Client::Build: rails/rails#15143>}

分支 API 可用于获取有关给定分支上的最新构建的信息。

属性

请参阅 构建。

列出分支

这将列出最新的 25 个分支。

GET /repos/{repository.id}/branches

GET /repos/{+repository.slug}/branches

显示分支

GET /repos/{repository.id}/branches/{branch}

GET /repos/{+repository.slug}/branches/{branch}

广播

GET /broadcasts HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "broadcasts": [
    {
      "id": 42,
      "message": "We're switching our build infrastructure on April 29."
    }
  ]
}

$ travis raw /broadcasts
{"broadcasts"=>[{"id"=>451, "message"=>"This is a broadcast!"}]}

require 'travis'

Travis::Broadcast.current.each do |broadcast|
  puts broadcast.message
end

属性

属性 描述
id 广播 ID
message 广播消息

列出广播

GET /broadcasts

此请求始终需要进行身份验证。

构建

GET /repos/sinatra/sinatra/builds HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "builds": [
    {
      "commit_id": 6534711,
      "config": { },
      "duration": 2648,
      "finished_at": "2014-04-08T19:52:56Z",
      "id": 22555277,
      "job_ids": [22555278, 22555279, 22555280, 22555281],
      "number": "784",
      "pull_request": true,
      "pull_request_number": "1912",
      "pull_request_title": "Example PR",
      "repository_id": 82,
      "started_at": "2014-04-08T19:37:44Z",
      "state": "failed"
    }
  ],
  "jobs": [ ],
  "commits": [ ]
}

$ travis history
...
$ travis show 15 # show build #15
...
$ travis restart 15
...
$ travis cancel 15
...

require 'travis'
Travis.access_token = 'YOUR TRAVIS ACCESS TOKEN'

repository = Travis::Repository.find('my/repo')
repository.each_build do |build|
  # restart all the builds
  build.restart
end

属性

属性 描述
id 构建 ID
repository_id 存储库 ID
commit_id 提交 ID
number 构建编号
pull_request true 或 false
pull_request_title 如果 pull_request 为 true，则为 PR 标题
pull_request_number 如果 pull_request 为 true，则为 PR 编号
config 构建配置（已删除安全值和 SSH 密钥）
state 构建状态
started_at 构建开始时间
finished_at 构建完成时间
duration 构建持续时间
job_ids 构建矩阵中的作业 ID 列表

请注意，如果构建在稍后重新启动，duration 可能与 finished_at - started_at 不一致。

列出构建

GET /builds

参数 默认值 描述
ids 要获取的构建 ID 列表
repository_id 构建所属的存储库 ID
slug 构建所属的存储库 slug
number 按构建编号过滤，需要 slug 或 repository_id
after_number 列出给定构建编号之后的构建（用于分页），需要 slug 或 repository_id
event_type 将构建限制为给定的事件类型（push 或 pull_request）

您必须提供 ids、repository_id 或 slug 之一。

GET /repos/{repository.id}/builds

参数 默认值 描述
number 按构建编号过滤
after_number 列出给定构建编号之后的构建（用于分页）
event_type 将构建限制为给定的事件类型（push 或 pull_request）

GET /repos/{+repository.slug}/builds

参数 默认值 描述
number 按构建编号过滤
after_number 列出给定构建编号之后的构建（用于分页）
event_type 将构建限制为给定的事件类型（push 或 pull_request）

显示构建

GET /builds/{build.id}

GET /repos/{repository.id}/builds/{build.id}

GET /repos/{+repository.slug}/builds/{build.id}

取消构建

POST /builds/{build.id}/cancel

此请求始终需要进行身份验证。

重新启动构建

POST /builds/{build.id}/restart

此请求始终需要进行身份验证。

缓存

GET /repos/travis-pro/billing/caches HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.com

HTTP/1.1 200 OK
Content-Type: application/json

{
  "caches": [
    {
      "repository_id": 51007,
      "size": 103677795,
      "slug": "cache--rvm-2.0.0--gemfile-Gemfile",
      "branch": "master",
      "last_modified": "2014-03-06T16:19:49Z"
    }
  ]
}

$ travis cache -r travis-pro/billing
On branch master:
cache--rvm-2.0.0--gemfile-Gemfile  last modified: 2014-03-06 11:19:49  size: 98.87 MiB

On branch mm-ruby-2.1:
cache--rvm-2.0.0--gemfile-Gemfile  last modified: 2013-12-28 09:42:21  size: 98.87 MiB
cache--rvm-2.1.0--gemfile-Gemfile  last modified: 2013-12-28 09:42:21  size: 88.02 MiB

Overall size of above caches: 371.08 MiB

$ travis cache -r travis-pro/billing --delete --branch mm-ruby-2.1

require 'travis'

repository = Travis::Repository.find('travis-pro/billing')
repository.caches.each do |cache|
  # delete all caches!
  cache.delete if cache.branch == 'mm-ruby-2.1'
end

# or in a single request
repository.delete_caches(branch: 'mm-ruby-2.1')

属性

属性 描述
repository_id 缓存所属的存储库的 ID
size 压缩后的缓存大小（以字节为单位）
slug 缓存 slug（根据 env 生成）
branch 缓存所属的分支
last_modified 缓存最后更新时间

列出缓存

GET /repos/{repository.id}/caches

GET /repos/{+repository.slug}/caches

参数 默认值 描述
branch 将列出的缓存限制为给定分支上的缓存
match 将列出的缓存限制为 slug 包含给定值的缓存

此请求始终需要进行身份验证。

删除缓存

DELETE /repos/{repository.id}/caches

DELETE /repos/{+repository.slug}/caches

参数 默认值 描述
branch 仅删除给定分支上的缓存
match 仅删除 slug 包含给定值的缓存

此请求始终需要进行身份验证。

提交

GET /repos/sinatra/sinatra/builds HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "builds": [ ],
  "jobs": [ ],
  "commits": [
    {
      "id": 118789812,
      "sha": "180158b725b8a964711ef8bdb3c8cbaf53d2e6a3",
      "branch": "master",
      "tag": null,
      "message": "Merge pull request #1452 from greysteil/metadata-link\n\nAdd metadata link to gemspec",
      "committed_at": "2018-06-24T16:50:16Z",
      "author_name": "namusyaka",
      "author_email": "namusyaka@gmail.com",
      "committer_name": "GitHub",
      "committer_email": "noreply@github.com",
      "compare_url": "https://github.com/sinatra/sinatra/compare/1caeafec67e9...180158b725b8",
      "pull_request_number": null
    }
  ]
}

$ travis history -r sinatra/sinatra
#784 failed:     master Merge pull request #861 from kant/patch-1
#783 passed:     v1.4.5 v1.4.5
#782 passed:     master v1.4.5

require 'travis'

repository = Travis::Repository.find('my/repo')
repository.each_build do |build|
  puts build.commit.message
end

没有用于解析提交的 API 端点，但是提交数据可能包含在其他 API 响应中，例如 构建 或 作业。

属性

属性 描述
id 提交 ID
sha 提交 sha
branch 提交所在的 branches
message 提交消息
committed_at 提交日期
author_name 作者姓名
author_email 作者电子邮件
committer_name 提交者姓名
committer_email 提交者电子邮件
compare_url GitHub 上的差异链接

钩子

PUT /hooks HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.org
Content-Type: application/json

{
  "hook": {
    "id": 42,
    "active": true
  }
}

$ travis enable -r my/repo

require 'travis'
Travis.access_token = 'YOUR TRAVIS ACCESS TOKEN'
Travis.hooks.each { |hook| hook.enable }

属性

请参阅 存储库。

列出钩子

GET /hooks

此请求始终需要进行身份验证。

启用/禁用钩子

PUT /hooks

参数 默认值 描述
hook[id] 钩子/存储库的 ID
hook[active] false 是否启用钩子（true）或禁用钩子（false）

PUT /hooks/{hook.id}

参数 默认值 描述
hook[active] false 是否启用钩子（true）或禁用钩子（false）

此请求始终需要进行身份验证。

作业

POST /jobs/42/restart HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.org

$ travis restart 1.2 -r my/repo

require 'travis'
Travis.access_token = 'YOUR TRAVIS ACCESS TOKEN'

Travis.repos('my/repo').last_build.jobs.each do |job|
  job.restart if job.failed?
end

属性

属性 描述
id 作业 ID
build_id 构建 ID
repository_id 存储库 ID
commit_id 提交 ID
log_id 日志 ID
number 作业编号
config 作业配置（已删除安全值和 SSH 密钥）
state 作业状态
started_at 作业开始时间
finished_at 作业完成时间
queue 作业队列
allow_failure 作业状态是否影响构建状态

获取作业

GET /jobs/{job.id}

获取多个作业

参数 默认值 描述
ids 作业 ID 列表
state 要过滤的作业状态
queue 要过滤的作业队列

您需要提供上述参数中的一个。如果您提供 state 或 queue，则最多返回 250 个作业。

取消作业

POST /jobs/{job.id}/cancel

此请求始终需要进行身份验证。

重新启动作业

POST /jobs/{job.id}/restart

此请求始终需要进行身份验证。

日志

GET /jobs/42/log HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: text/plain
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type text/plain

Using worker: ...

$ travis logs
... logs ...

require 'travis'

rails = Travis::Repository.find('rails/rails')
job   = rails.last_build.jobs.first

# this will live stream if the job is currently running
job.log.body do |part|
  print part
end

属性

属性 描述
id 日志 ID
作业 ID 作业 ID
主体 日志主体

分块属性

您可以通过在 Accept 头部中指定的 MIME 类型中添加属性 chunked=true 来检索分块属性，而不是正常属性。

属性 描述
id 日志 ID
作业 ID 作业 ID
部分 日志部分

The parts 将是一个包含以下属性的 JSON 对象数组。

属性 描述
number 部分编号
内容 部分内容

获取日志

GET /logs/{log.id}

获取日志作为纯文本

GET /jobs/{job.id}/logs

这在日志已归档的情况下可能需要，在这种情况下它将导致重定向。

流式日志

要流式传输日志，您必须在 Pusher 上订阅日志所属作业的频道（频道是 job-{job.id}），并监听 job:log 事件。有效载荷将具有与分块属性 API 有效载荷中的部分相同的格式。

权限

GET /users/permissions HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "permissions": [1, 2, 3],
  "admin": [1, 2],
  "pull": [],
  "push": [3]
}

$ travis repos

require 'travis'
Travis.access_token = 'YOUR TRAVIS ACCESS TOKEN'

Travis.user.push_access.each do |repo|
  puts "has push access to #{repo.slug}"
end

权限端点将返回存储库 ID 数组

键 ID 用于
权限 用户有权访问的存储库
管理员 用户具有管理员访问权限的存储库
拉取 用户具有拉取访问权限的存储库
推送 用户具有推送访问权限的存储库

拉取访问列表仅与私有项目相关。

获取权限

GET /users/permissions

此请求始终需要进行身份验证。

存储库密钥

GET /repos/sinatra/sinatra/key HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "-----BEGIN RSA PUBLIC KEY-----\\nMIGJAoGBAOcx131amMqIzm5+FbZz+DhIgSDbFzjKKpzaN5UWVCrLSc57z64xxTV6\\nkaOTZmjCWz6WpaPkFZY+czfL7lmuZ/Y6UNm0vupvdZ6t27SytFFGd1/RJlAe89tu\\nGcIrC1vtEvQu2frMLvHqFylnGd5Gy64qkQT4KRhMsfZctX4z5VzTAgMBAAE=\\n-----END RSA PUBLIC KEY-----\\n",
  "fingerprint": "ef:39:56:6e:2a:09:a2:10:2e:b5:39:ac:3d:3e:e1:05"
}

$ travis pubkey -r travis-ci/travis-api
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCOmOkC6MYRH1w2ib3AIC00GNwmgr8ch3mNHZ16x6cvSMjc6cURZt9Hav6gz03P5+9e5Vw1ztm3hvPR+IJsyOV/CSsYf1Cgboj6ZJ7tr3xOJXcqcMVfiGiG7Km6/psRdn0jrjTpU/qcru8Wx3zbQEf5NuXQyMVHmnl8/5w0WPV/Uw==

$ travis pubkey --pem -r travis-ci/travis-api
-----BEGIN RSA PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCOmOkC6MYRH1w2ib3AIC00GNwm
gr8ch3mNHZ16x6cvSMjc6cURZt9Hav6gz03P5+9e5Vw1ztm3hvPR+IJsyOV/CSsY
f1Cgboj6ZJ7tr3xOJXcqcMVfiGiG7Km6/psRdn0jrjTpU/qcru8Wx3zbQEf5NuXQ
yMVHmnl8/5w0WPV/UwIDAQAB
-----END RSA PUBLIC KEY-----

$ travis pubkey --fingerprint -r travis-ci/travis-api
99:66:93:03:41:0b:f1:f7:61:83:16:61:fa:47:c0:8f

require 'travis'
repo = Travis::Repository.find('travis-ci/travis-api')

puts "SSH format:  ", repo.key.to_ssh
puts "PEM format:  ", repo.key.to_s
puts "Fingerprint: ", repo.key.fingerprint
puts repository.encrypt("example")
属性 描述
密钥 公钥
指纹 公钥指纹

此密钥可用于加密（但不能解密）安全环境变量。

获取公钥

GET /repos/{repository.id}/key

GET /repos/{+repository.slug}/key

生成公钥

POST /repos/{repository.id}/key

POST /repos/{+repository.slug}/key

这将使当前密钥失效，从而也使所有加密的变量失效。

此请求始终需要进行身份验证。

存储库

GET /repos/sinatra/sinatra HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "repo": {
    "id": 82,
    "slug": "sinatra/sinatra",
    "description": "Classy web-development dressed in a DSL",
    "last_build_id": 23436881,
    "last_build_number": "792",
    "last_build_state": "passed",
    "last_build_duration": 2542,
    "last_build_started_at": "2014-04-21T15:27:14Z",
    "last_build_finished_at": "2014-04-21T15:40:04Z",
    "active": "true"
  }
}

$ travis show -r travis-ci/travis-api
...

require 'travis'
repos = Travis::Repository.find_all(owner_name: 'sinatra')
repos.each do |repo|
  puts repo.slug
end

属性

属性 描述
id 存储库 ID
slug 存储库标识
描述 GitHub 上的描述
last_build_id 最后一次构建的构建 ID
last_build_number 最后一次构建的构建号
last_build_state 最后一次构建的构建状态
last_build_duration 最后一次构建的构建持续时间
last_build_started_at 最后一次构建的构建开始时间
last_build_finished_at 最后一次构建的构建结束时间
active 存储库的活动状态

获取存储库

GET /repos/{repository.id}

GET /repos/{+repository.slug}

查找存储库

参数 默认值 描述
ids 要获取的存储库 ID 列表，不能与其他参数组合
成员 按有权访问的用户进行筛选（GitHub 登录名）
owner_name 按所有者名称进行筛选（标识的第一个部分）
slug 按标识进行筛选
搜索 按搜索词进行筛选
active false 如果 true，将仅返回已启用的存储库。

如果没有给出参数，则返回一个具有最近活动的存储库列表。

请求

GET /requests/6301283 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "request": {
    "id": 6301283,
    "repository_id": 1121945,
    "commit_id": 5904016,
    "created_at": "2014-03-08T15:54:07Z",
    "owner_id": 4279,
    "owner_type": "Organization",
    "event_type": "push",
    "result": "accepted",
    "pull_request": false,
    "branch": "feat-container-injector"
  },
  "commit": {
    "id": 5904016,
    "sha": "09e2ce14f1debea64a1122851fc3f8f1c1a18ebc",
    "branch": "feat-container-injector",
    "message": "don't inject the service_container",
    "committed_at": "2014-03-08T15:53:42Z",
    "author_name": "Sebastiaan Stok",
    "author_email": "s.stok@rollerscapes.net",
    "committer_name": "Sebastiaan Stok",
    "committer_email": "s.stok@rollerscapes.net",
    "compare_url": "https://github.com/..."
  }
}

$ travis requests -r my/repo
...

require 'travis'

Travis::Repository.find('sinatra/sinatra').requests.each do |request|
  puts "#{request.commit.sha}: #{request.result}"
end

请求可用于查看 GitHub 事件是否以及为何触发了新的构建。

属性

属性 描述
id 请求 ID
commit_id 提交 ID
repository_id 存储库 ID
created_at 创建时间
owner_id 所有者 ID
owner_type 所有者类型 ("User" 或 "Organization")
event_type 事件类型 ("push" 或 "pull_request")
base_commit 拉取请求的基本提交
head_commit 拉取请求的头部提交
结果 "accepted", "rejected" 或 null
message 人类可读的消息，解释了事件为何被拒绝
pull_request true 或 false
pull_request_number 拉取请求号
pull_request_title 拉取请求标题
branch 提交所在的的树枝
标签 如果提交已标记，则为标记

显示请求

GET /requests/{request.id}

列出请求

GET /requests

参数 默认值 描述
repository_id 请求所属的存储库 ID
slug 请求所属的存储库标识
限制 25 要返回的最大请求数（不能大于 100）
older_than 列出在 older_than 之前（older_than 为请求 ID）的请求

您必须提供 repository_id 或 slug。

设置：常规

GET /repos/82/settings HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "settings": {
    "builds_only_with_travis_yml": true,
    "build_pushes": true,
    "build_pull_requests": true,
    "maximum_number_of_builds": 0
  }
}

$ travis settings
Settings for travis-ci/travis-api:
[-] builds_only_with_travis_yml    Only run builds with a .travis.yml
[+] build_pushes                   Build pushes
[+] build_pull_requests            Build pull requests
  0 maximum_number_of_builds       Maximum number of concurrent builds

$ travis settings build_pull_requests --enable

require 'travis'
Travis.access_token = 'YOUR TRAVIS ACCESS TOKEN'
repo = Travis::Repository.find('my/repo')
repo.settings.build_pull_requests = false
repo.settings.save

属性

属性 描述
builds_only_with_travis_yml “仅构建具有 .travis.yml 的构建”设置 (true 或 false)
build_pushes “构建推送”设置 (true 或 false)
build_pull_requests “构建拉取请求”设置 (true 或 false)
maximum_number_of_builds “最大并发构建数”设置（整数）

检索设置

GET /repos/{repository.id}/settings

此请求始终需要进行身份验证。

更新设置

PATCH /repos/{repository.id}/settings

参数 默认值 描述
设置 {} 应更新的设置的哈希映射及其新值（参见属性）

此请求始终需要进行身份验证。

设置：环境变量

GET /settings/env_vars?repository_id=124920 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "env_vars":[
    {
      "id": "018e66f2-cd3a-4295-aa1d-018fe9aa0fb4",
      "name": "example",
      "value": "foobar",
      "public": true,
      "repository_id": 124920
    },
    {
      "id": "ec9423da-9658-4cd6-b282-fd0e5f6ed2df",
      "name": "secret_example",
      "public": false,
      "repository_id": 124920
    }
  ]
}

$ travis env list
example=foobar
secret_example=[secure]

require 'travis'
Travis.access_token  = 'YOUR TRAVIS ACCESS TOKEN'
repo                 = Travis::Repository.find('my/repo')
repo.env_vars['foo'] = bar

属性

属性 描述
id 环境变量 ID
repository_id 存储库 ID
name 环境变量名称（导出）
值 环境变量值（导出，仅在 public 为 true 时包含）
公共 值是否公开

列出变量

GET /repos/settings/env_vars?repository_id={repository.id}

此请求始终需要进行身份验证。

获取变量

GET /repos/settings/env_vars/{env_var.id}?repository_id={repository.id}

此请求始终需要进行身份验证。

添加变量

POST /repos/settings/env_vars?repository_id={repository.id}

参数 默认值 描述
env_var 环境变量变量的哈希映射（参见下文）
env_var.name 新环境变量的名称（字符串）
env_var.value 新环境变量的值（字符串）
env_var.public false 是否显示值

此请求始终需要进行身份验证。

更新变量

PATCH /repos/settings/env_vars/{env_var.id}

参数 默认值 描述
env_var 环境变量变量的哈希映射（参见下文）
env_var.name 当前值 新环境变量的名称（字符串）
env_var.value 当前值 新环境变量的值（字符串）
env_var.public 当前值 是否显示值

此请求始终需要进行身份验证。

删除变量

DELETE /repos/settings/env_vars/{env_var.id}

此请求始终需要进行身份验证。

设置：SSH 密钥

GET /settings/ssh_key/124920 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.com

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ssh_key": {
    "description": "my custom key",
    "fingerprint": "99:66:93:03:41:0b:f1:f7:61:83:16:61:fa:47:c0:8f"
  }
}

$ travis sshkey
No custom SSH key installed.

require 'travis/pro'
Travis::Pro.access_token = 'YOUR TRAVIS ACCESS TOKEN'
puts Travis::Pro::Repository.find('my/repo').ssh_key.description

属性

属性 描述
id SSH 密钥 ID（对应于存储库 ID）
描述 密钥描述
指纹 密钥指纹

获取密钥

GET /settings/ssh_key/#{ssh_key.id}

此请求始终需要进行身份验证。

更新或创建密钥

PATCH /settings/ssh_key/#{ssh_key.id}

参数 默认值 描述
ssh_key SSH 密钥数据的哈希映射（参见下文）
ssh_key.description 当前值或为空 密钥描述
ssh_key.value 私钥（必需）

此请求始终需要进行身份验证。

删除密钥

DELETE /settings/ssh_key/#{ssh_key.id}

此请求始终需要进行身份验证。

用户

GET /users/ HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Authorization: token YOUR TRAVIS ACCESS TOKEN
Host: api.travis-ci.org

HTTP/1.1 200 OK
Content-Type: application/json

{
  "user": {
    "id": 267,
    "name": "Konstantin Haase",
    "login": "rkh",
    "email": "github@rkh.im",
    "gravatar_id": "5c2b452f6eea4a6d84c105ebd971d2a4",
    "is_syncing": false,
    "synced_at": "2014-02-27T18:53:43Z",
    "correct_scopes": false,
    "created_at": "2011-03-30T16:25:21Z"
  }
}

$ travis whoami
You are rkh (Konstantin Haase)

$ travis sync
synchronizing: ... done

require 'travis'
Travis.access_token = 'YOUR TRAVIS ACCESS TOKEN'
puts Travis.user.name
Travis.user.sync

属性

属性 描述
id 用户 ID
login GitHub 上的用户登录名
name GitHub 上的用户名
电子邮件 GitHub 上的主要电子邮件地址
gravatar_id 头像 ID
is_syncing 用户帐户是否正在同步
synced_at 上次同步时间
correct_scopes GitHub 令牌是否具有正确的范围
频道 此用户的 Pusher 频道

显示用户

GET /users/

GET /users/{user.id}

此请求始终需要进行身份验证。

同步用户

POST /users/sync

触发与 GitHub 的新同步。如果用户当前正在同步，则可能返回状态 409。

此请求始终需要进行身份验证。

其他端点

代码整理

PUT /lint/ HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2.1+json
Host: api.travis-ci.org
Content-Type: text/yaml

language: ruby
jdk: default

HTTP/1.1 200 OK
Content-Type: application/json

{
  "lint": {
    "warnings": [
      {
        "key": ["jdk"],
        "message": "specified jdk, but ruby does not include jruby"
      }
    ]
  }
}

$ travis lint example.yml
Warnings for example.yml:
[x] dropping jdk section: specified jdk, but ruby does not include jruby

require 'travis'

content = <<-YAML
  language: ruby
  jdk: default
YAML

Travis.lint(content).warnings.each do |warning|
  puts "%p: %s" % [warning.key, warning.message]
end

POST /lint

参数 默认值 描述
内容 .travis.yml 的内容

PUT /lint

这是使用参数的 POST 的替代端点，使其可以与 curl (curl -T .travis.yml api.travis-ci.org/lint) 等工具配合使用。请求主体可以直接包含 YAML 文件。

API 客户端

有一些 API 客户端可以用于与 Travis API 交互，而不是手动触发 HTTP 请求并解析响应。

官方

以下客户端由 Travis CI 团队维护

Web 浏览器

使用 CORS 的 API 请求

<script>
  // using XMLHttpRequest or XDomainRequest to send an API request
  var req = window.XDomainRequest ? new XDomainRequest() : new XMLHttpRequest();

  if(req) {
    req.open("GET", "https://api.travis-ci.org/", true);
    req.onreadystatechange = function() { alert("it worked!") };
    req.setRequestHeader("Accept", "application/vnd.travis-ci.2.1+json");
    req.send();
  }
</script>

使用 jQuery

<script>
$.ajax({
  url: "https://api.travis-ci.org/",
  headers: { Accept: "application/vnd.travis-ci.2.1+json" },
  success: function() { alert("it worked!") }
});
</script>

JSONP

<script>
  function jsonpCallback() { alert("it worked!") };
</script>
<script src="https://api.travis-ci.org/?callback=jsonpCallback"></script>

在编写浏览器内客户端时，您必须绕过浏览器的 同源策略。通常，我们为此提供两种不同的方法：跨域资源共享（也称为 CORS）和 JSONP。如果您没有充分的理由使用 JSONP，建议您使用 CORS。

跨域资源共享

所有 API 资源都设置了适当的标头以允许跨域请求。请注意，在 Internet Explorer 上，您可能需要使用不同的界面来发送这些请求。

与 JSONP 相比，CORS 不会导致执行任何不受信任的代码。

大多数 JavaScript 框架（如 jQuery）会在后台为您处理 CORS 请求，因此您只需执行正常的 ajax 请求即可。

我们当前的设置允许标头 Content-Type、Authorization、Accept 和 HTTP 方法 HEAD、GET、POST、PATCH、PUT、DELETE。

JSONP

您可以通过将响应视为 JavaScript 来禁用同源策略。提供一个 callback 参数来使用它。

这有可能导致代码注入，请谨慎使用。

第三方

除了官方客户端外，还有许多第三方客户端可用，其中包括