使用 API V3 触发构建

Travis CI 托管解决方案 (app.travis-ci.com) #

通过向 /repo/{slug|id}/requests 发送 POST 请求，使用 API V3 触发 Travis CI 构建。

1. 从您的 Travis CI 设置页面 获取 API 令牌。您需要此令牌才能对大多数 API 请求进行身份验证。

   您还可以使用 Travis CI 命令行客户端 获取您的 API 令牌。

   travis login --com --github-token YOUR_GITHUB_TOKEN
   travis token --com
   

2. 向 API 发送请求。此示例 shell 脚本向 /repo/travis-ci/travis-core/requests 发送 POST 请求，以触发 travis-ci/travis-core 存储库 master 分支的特定提交（省略 sha 表示最新提交）的构建。

   body='{
   "request": {
   "branch":"master",
   "sha":"bf944c952724dd2f00ff0c466a5e217d10f73bea"
   }}'
   
   curl -s -X POST \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H "Travis-API-Version: 3" \
      -H "Authorization: token xxxxxx" \
      -d "$body" \
      https://api.travis-ci.com/repo/travis-ci%2Ftravis-core/requests
   

   请求 URL 中的 %2F 是必需的，以便存储库 slug 中的所有者和存储库名称被解释为单个 URL 段。

   构建使用 master 分支中的 .travis.yml 文件，但您可以添加或覆盖配置，或更改提交消息。覆盖任何部分（例如 script 或 env）会覆盖整个部分，.travis.yml 文件的内容 *不会* 与请求中包含的值合并。

3. 向 API 发送更复杂的请求。以下脚本触发构建，并为提交传递 message 属性，并通过传递环境变量和脚本命令来添加构建配置。这里，来自 .travis.yml 文件的配置 *将* 与来自请求主体的配置合并。

   请求配置中的键会覆盖 .travis.yml 中存在的任何键。

   body='{
    "request": {
    "message": "Override the commit message: this is an api request",
    "branch":"master",
    "merge_mode": "deep_merge",
    "config": {
      "env": {
        "jobs": [
          "TEST=unit"
        ]
      },
      "script": "echo FOO"
     }
   }}'
   
   curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Travis-API-Version: 3" \
    -H "Authorization: token xxxxxx" \
    -d "$body" \
    https://api.travis-ci.com/repo/travis-ci%2Ftravis-core/requests
   

4. 查看响应主体，其中包含有关构建、存储库和用户的信息。

   {
     "@type": "pending",
     "remaining_requests": 1,
     "repository": {
       "@type": "repository",
       "@href": "/repo/39521",
       "@representation": "minimal",
       "id": 39521,
       "name": "test-2",
       "slug": "svenfuchs/test-2"
     },
     "request": {
       "repository": {
         "id": 44258138,
         "owner_name": "svenfuchs",
         "name": "test-2"
       },
       "user": {
         "id": 3664
       },
       "id": 205729,
       "message": null,
       "branch": "master",
       "config": {
         ...
       }
     },
     "resource_type": "request"
   }
   

5. 访问 API V3 资源管理器，以获取有关可用端点以及您可以使用它们执行的操作的更多信息。

如果您的 API 或 cron 触发的构建在 *同一提交或分支* 上反复运行，您会注意到 GitHub 对每个提交有 1000 个状态更新 的限制，这会导致 Travis CI 构建状态在 GitHub 上显示不正确。通过为您的自动化构建指定一个定期更新的分支来避免此问题。

Travis CI 企业版 #

通过向 /repo/{slug|id}/requests 发送 POST 请求，在您的 Travis CI 企业版实例上使用 API 触发 Travis CI 构建。

1. 从您的 Travis CI 企业版 (https://PLATFORM_URL/account/preferences) 获取 API 令牌。您需要此令牌才能对大多数 API 请求进行身份验证。

   您还可以使用 Travis CI 命令行客户端 获取您的 API 令牌。

   travis login -X --github-token YOUR_GITHUB_TOKEN
   travis token -X
   

2. 向 API 发送请求。此示例 shell 脚本向 /repo/travis-ci/tcie-demo/requests 发送 POST 请求，以触发 travis-ci/tcie-demo 存储库 master 分支的特定提交（省略 sha 表示最新提交）的构建。

   body='{
   "request": {
   "branch":"master",
   "sha":"bf944c952724dd2f00ff0c466a5e217d10f73bea"
   }}'
   
   curl -s -X POST \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H "Travis-API-Version: 3" \
      -H "Authorization: token xxxxxx" \
      -d "$body" \
      https://PLATFORM_URL/api/repo/travis-ci%2Ftcie-demo/requests
   

   请求 URL 中的 %2F 是必需的，以便存储库 slug 中的所有者和存储库名称被解释为单个 URL 段。 PLATFORM_URL 是您的 Travis CI 企业版实例可访问的端点。

   构建使用 master 分支中的 .travis.yml 文件，但您可以添加或覆盖配置，或更改提交消息。覆盖任何部分（例如 script 或 env）会覆盖整个部分，存储库中存在的 .travis.yml 文件的内容 *不会* 与请求中包含的值合并。

自定义提交消息 #

您可以在请求主体中指定提交消息。

body='{
  "request": {
    "branch":"master",
    "message": "Override the commit message: this is an api request"
    ...
  }
}'

合并模式 #

合并模式控制如何将您 .travis.yml 中的构建配置合并（组合）到您 POST 请求随附的构建配置中。

以下列出可用的合并模式：

• deep_merge_append
• deep_merge_prepend
• deep_merge
• merge
• replace

默认合并模式为 deep_merge_append，并启用 构建配置验证。如果禁用构建配置验证，则默认为 deep_merge，该模式将很快停止使用。

建议您在 API 请求中明确指定合并模式。

请考虑以下示例：

# build config sent via API
{
  "env": [
    "API=true"
  ],
  "cache": {
    "directories": [
      "./one"
    ]
  },
  "addons": {
    "snap": "snap"
  }
}

# build config in your .travis.yml file
env:
- TRAVIS_YML=true
cache:
  apt: true
addons:
  apt:
    packages:
    - cmake

深度合并追加/预置 #

合并模式 deep_merge_append 和 deep_merge_prepend 会递归合并包含映射（哈希）的部分（键），并通过追加或预置到导入配置中的序列来连接序列（数组）。

给定合并模式 deep_merge_append，使用上述示例构建配置，结果将为：

{
  "env": [
    "TRAVIS_YML=true",
    "API=true"
  ],
  "cache": {
    "apt": true,
    "directories": [
      "./one"
    ]
  },
  "addons": {
    "snap": "snap",
    "apt": {
      "packages": [
        "cmake"
      ]
    }
  }
}

给定合并模式 deep_merge_prepend，使用上述示例构建配置，结果将为：

{
  "env": [
    "API=true",
    "TRAVIS_YML=true"
  ],
  "cache": {
    "apt": true,
    "directories": [
      "./one"
    ]
  },
  "addons": {
    "snap": "snap",
    "apt": {
      "packages": [
        "cmake"
      ]
    }
  }
}

深度合并 #

合并模式 deep_merge 会递归合并包含映射（哈希）的部分（键），但会覆盖序列（数组）。

给定合并模式 deep_merge，使用上述示例构建配置，结果将为：

{
  "env": [
    "API=true"
  ],
  "cache": {
    "apt": true,
    "directories": [
      "./one"
    ]
  },
  "addons": {
    "snap": "snap",
    "apt": {
      "packages": [
        "cmake"
      ]
    }
  }
}

合并 #

合并模式 merge 执行浅层合并。

这意味着在您的 .travis.yml 中定义的根级部分（键）将覆盖导入文件中也存在的根级部分（键）。

给定合并模式 merge，使用上述示例构建配置，结果将如下所示。顶级键 cache 和 addons 将替换 .travis.yml 中的键。

{
  "env": [
    "API=true"
  ],
  "cache": {
    "apt": true
  },
  "addons": {
    "snap": "snap"
  }
}

替换 #

合并模式 replace 指示 Travis CI 仅用 API 请求随附的配置替换 .travis.yml 文件中的构建配置。

{
  "env": [
    "API=true"
  ],
  "cache": {
    "directories": [
      "./one"
    ]
  },
  "addons": {
    "snap": "snap"
  }
}