跳至主要内容
REST API 现在已版本化。 有关详细信息,请参阅“关于 API 版本控制”。

用于部署的 REST API 端点

使用 REST API 创建和删除部署及部署环境。

关于部署

部署是对部署特定引用(分支、SHA、标签)的请求。GitHub 调度外部服务可以监听并采取行动的 deployment 事件,当创建新部署时。部署使开发人员和组织能够围绕部署构建松散耦合的工具,而无需担心交付不同类型应用程序(例如,Web、本机)的实现细节。

部署状态允许外部服务使用 errorfailurependingin_progressqueuedsuccess 状态标记部署,监听 deployment_status 事件 的系统可以消耗这些状态。

部署状态还可以包括可选的 descriptionlog_url,强烈建议使用它们,因为它们使部署状态更有用。log_url 是部署输出的完整 URL,description 是部署发生情况的高度概括。

当创建新的部署和部署状态时,GitHub 会派发 deploymentdeployment_status 事件。这些事件允许第三方集成接收并响应部署请求,并在部署进行时更新部署状态。

下面是一个关于这些交互如何工作的简单顺序图。

+---------+             +--------+            +-----------+        +-------------+
| Tooling |             | GitHub |            | 3rd Party |        | Your Server |
+---------+             +--------+            +-----------+        +-------------+
     |                      |                       |                     |
     |  Create Deployment   |                       |                     |
     |--------------------->|                       |                     |
     |                      |                       |                     |
     |  Deployment Created  |                       |                     |
     |<---------------------|                       |                     |
     |                      |                       |                     |
     |                      |   Deployment Event    |                     |
     |                      |---------------------->|                     |
     |                      |                       |     SSH+Deploys     |
     |                      |                       |-------------------->|
     |                      |                       |                     |
     |                      |   Deployment Status   |                     |
     |                      |<----------------------|                     |
     |                      |                       |                     |
     |                      |                       |   Deploy Completed  |
     |                      |                       |<--------------------|
     |                      |                       |                     |
     |                      |   Deployment Status   |                     |
     |                      |<----------------------|                     |
     |                      |                       |                     |

请记住,GitHub 实际上从未访问过您的服务器。由您的第三方集成与部署事件进行交互。多个系统可以侦听部署事件,由这些系统中的每一个决定它们是否负责将代码推送到您的服务器、构建本机代码等。

请注意,repo_deployment OAuth 范围授予对部署和部署状态的目标访问权限,授予对存储库代码的访问权限,而 public_reporepo 范围也授予对代码的访问权限。

非活动部署

当您将部署的状态设置为 success 时,同一存储库中具有相同环境名称的所有先前非瞬态、非生产环境部署将变为 inactive。为避免这种情况,您可以在创建部署状态时将 auto_inactive 设置为 false

您可以通过将瞬态环境的 state 设置为 inactive 来传达该环境已不存在。将 state 设置为 inactive 会在 GitHub 中显示部署为 destroyed,并取消对它的访问。

列出部署

可以通过查询参数对部署进行简单的筛选

用于“列出部署”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限设置

  • “部署”存储库权限(读取)

如果仅请求公共资源,则无需身份验证或上述权限即可使用此端点。

“列出部署”的参数

标头
名称、类型、说明
accept 字符串

建议设置为 application/vnd.github+json

路径参数
名称、类型、说明
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不带 .git 扩展名的存储库名称。名称不区分大小写。

查询参数
名称、类型、说明
sha 字符串

创建时记录的 SHA。

默认值: none

ref 字符串

引用名称。可以是分支、标记或 SHA。

默认值: none

task 字符串

部署任务的名称(例如,deploydeploy:migrations)。

默认值: none

environment 字符串或 null

已部署到的环境的名称(例如,stagingproduction)。

默认值: none

per_page 整数

每页的结果数(最大 100)。有关详细信息,请参阅“在 REST API 中使用分页”。

默认值: 30

page 整数

要获取的结果的页码。有关详细信息,请参阅“在 REST API 中使用分页”。

默认值: 1

“列出部署”的 HTTP 响应状态代码

状态代码说明
200

OK

“列出部署”的代码示例

请求示例

get/repos/{owner}/{repo}/deployments
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/deployments

响应

状态:200
[ { "url": "https://api.github.com/repos/octocat/example/deployments/1", "id": 1, "node_id": "MDEwOkRlcGxveW1lbnQx", "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d", "ref": "topic-branch", "task": "deploy", "payload": {}, "original_environment": "staging", "environment": "production", "description": "Deploy request from hubot", "creator": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "created_at": "2012-07-20T01:19:13Z", "updated_at": "2012-07-20T01:19:13Z", "statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses", "repository_url": "https://api.github.com/repos/octocat/example", "transient_environment": false, "production_environment": true } ]

创建部署

部署提供了几个可配置参数,并具有某些默认值。

ref 参数可以是任何命名的分支、标签或 SHA。在 GitHub 上,我们通常部署分支并在合并拉取请求之前对其进行验证。

environment 参数允许将部署发布到不同的运行时环境。团队通常有多个环境来验证其应用程序,例如 productionstagingqa。此参数可以更轻松地跟踪请求部署的环境。默认环境为 production

auto_merge 参数用于确保请求的 ref 不落后于存储库的默认分支。如果 ref 落后于 存储库的默认分支,我们将尝试为您合并它。如果合并成功,API 将返回成功的合并提交。如果合并冲突阻止合并成功,API 将返回失败响应。

默认情况下,提交状态对于提交的每个上下文都必须处于 success 状态。required_contexts 参数允许您指定必须为 success 的上下文子集,或指定尚未提交的上下文。您不必使用提交状态进行部署。如果您不需要任何上下文或不创建任何提交状态,部署将始终成功。

payload 参数可用于部署系统可能需要的任何额外信息。它是一个 JSON 文本字段,将在分发部署事件时传递。

task 参数由部署系统使用,以允许不同的执行路径。在 Web 世界中,这可能是 deploy:migrations,用于在系统上运行架构更改。在编译的世界中,这可能是一个标志,用于编译启用了调试的应用程序。

合并分支响应

当 GitHub 自动将基本分支合并到主题分支中,而不是创建部署时,您将看到此响应。此自动合并发生在以下情况下

  • 存储库中启用了自动合并选项
  • 主题分支不包含基本分支上的最新更改,在响应示例中为master
  • 没有合并冲突

如果基本分支中没有新提交,则创建部署的新请求应给出成功的响应。

合并冲突响应

当启用auto_merge选项并且由于合并冲突,无法将默认分支(在本例中为master)合并到正在部署的分支(在本例中为topic-branch)时,会发生此错误。

提交状态检查失败

required_contexts参数指示一个或多个上下文需要具有success状态才能部署提交,但一个或多个必需的上下文没有success状态时,会发生此错误。

OAuth 应用程序令牌和个人访问令牌(经典)需要reporepo_deployment范围才能使用此端点。

“创建部署”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限设置

  • “部署”存储库权限(写入)

“创建部署”的参数

标头
名称、类型、说明
accept 字符串

建议设置为 application/vnd.github+json

路径参数
名称、类型、说明
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不带 .git 扩展名的存储库名称。名称不区分大小写。

正文参数
名称、类型、说明
ref string 必需

要部署的 ref。这可以是分支、标签或 SHA。

task 字符串

指定要执行的任务(例如,deploydeploy:migrations)。

默认值: deploy

auto_merge boolean

尝试将默认分支自动合并到请求的 ref 中(如果它落后于默认分支)。

默认值: true

required_contexts 字符串数组

要针对提交状态检查进行验证的 状态 上下文。如果您省略此参数,GitHub 会在创建部署之前验证所有唯一上下文。要完全绕过检查,请传递一个空数组。默认为所有唯一上下文。

payload 对象或字符串

包含有关部署的额外信息的 JSON 有效负载。

environment 字符串

目标部署环境的名称(例如,productionstagingqa)。

默认: production

description 字符串或 null

部署的简短描述。

默认: ""

transient_environment 布尔值

指定给定的环境是否特定于部署,并且在将来的某个时间点不再存在。默认值:false

默认: false

production_environment 布尔值

指定给定的环境是否是最终用户直接与之交互的环境。默认值:当 environmentproduction 时为 true,否则为 false

“创建部署”的 HTTP 响应状态代码

状态代码说明
201

已创建

202

合并分支响应

409

合并冲突或提交的状态检查失败时发生冲突

422

验证失败,或端点已遭垃圾邮件攻击。

“创建部署”的代码示例

请求示例

post/repos/{owner}/{repo}/deployments
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/deployments \ -d '{"ref":"topic-branch","payload":"{ \"deploy\": \"migrate\" }","description":"Deploy request from hubot"}'

简单示例

状态:201
{ "url": "https://api.github.com/repos/octocat/example/deployments/1", "id": 1, "node_id": "MDEwOkRlcGxveW1lbnQx", "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d", "ref": "topic-branch", "task": "deploy", "payload": {}, "original_environment": "staging", "environment": "production", "description": "Deploy request from hubot", "creator": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "created_at": "2012-07-20T01:19:13Z", "updated_at": "2012-07-20T01:19:13Z", "statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses", "repository_url": "https://api.github.com/repos/octocat/example", "transient_environment": false, "production_environment": true }

获取部署

“获取部署”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限设置

  • “部署”存储库权限(读取)

如果仅请求公共资源,则无需身份验证或上述权限即可使用此端点。

“获取部署”的参数

标头
名称、类型、说明
accept 字符串

建议设置为 application/vnd.github+json

路径参数
名称、类型、说明
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不带 .git 扩展名的存储库名称。名称不区分大小写。

deployment_id 整数 必需

deployment_id 参数

“获取部署”的 HTTP 响应状态代码

状态代码说明
200

OK

404

资源未找到

“获取部署”的代码示例

请求示例

get/repos/{owner}/{repo}/deployments/{deployment_id}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/deployments/DEPLOYMENT_ID

响应

状态:200
{ "url": "https://api.github.com/repos/octocat/example/deployments/1", "id": 1, "node_id": "MDEwOkRlcGxveW1lbnQx", "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d", "ref": "topic-branch", "task": "deploy", "payload": {}, "original_environment": "staging", "environment": "production", "description": "Deploy request from hubot", "creator": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "created_at": "2012-07-20T01:19:13Z", "updated_at": "2012-07-20T01:19:13Z", "statuses_url": "https://api.github.com/repos/octocat/example/deployments/1/statuses", "repository_url": "https://api.github.com/repos/octocat/example", "transient_environment": false, "production_environment": true }

删除部署

如果存储库只有一个部署,则无论其状态如何,你都可以删除该部署。如果存储库有多个部署,则你只能删除非活动部署。这可确保具有多个部署的存储库始终具有活动部署。

要将部署设置为非活动,你必须

  • 创建处于活动状态的新部署,以便系统记录当前状态,然后删除之前处于活动状态的部署。
  • 通过添加任何非成功部署状态将活动部署标记为非活动。

有关更多信息,请参阅“创建部署”和“创建部署状态”。

OAuth 应用程序令牌和个人访问令牌(经典)需要reporepo_deployment范围才能使用此端点。

“删除部署”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限设置

  • “部署”存储库权限(写入)

“删除部署”的参数

标头
名称、类型、说明
accept 字符串

建议设置为 application/vnd.github+json

路径参数
名称、类型、说明
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不带 .git 扩展名的存储库名称。名称不区分大小写。

deployment_id 整数 必需

deployment_id 参数

“删除部署”的 HTTP 响应状态代码

状态代码说明
204

无内容

404

资源未找到

422

验证失败,或端点已遭垃圾邮件攻击。

“删除部署”的代码示例

请求示例

delete/repos/{owner}/{repo}/deployments/{deployment_id}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/deployments/DEPLOYMENT_ID

响应

状态:204