部署环境的 REST API 端点 - GitHub 文档

关于部署环境

有关环境的更多信息，请参阅“管理部署环境”。若要管理环境机密，请参阅“GitHub Actions 机密的 REST API 端点”。

环境、环境机密和部署保护规则在所有当前 GitHub 计划的公共仓库中可用。它们在旧版计划（如青铜、白银或黄金）中不可用。要访问私有或内部仓库中的环境、环境机密和部署分支，您必须使用 GitHub Pro、GitHub Team 或 GitHub Enterprise。如果您使用的是 GitHub Free、GitHub Pro 或 GitHub Team 计划，其他部署保护规则（例如等待计时器或必填审阅者）仅适用于公共仓库。

列出环境

列出仓库的环境。

任何具有仓库读取权限的用户都可以使用此端点。

OAuth 应用令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点与私有仓库。

用于“列出环境”的细粒度访问令牌

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

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

“操作”仓库权限（读取）

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

“列出环境”的参数

标头
名称、类型、描述
`accept` 字符串建议设置为 `application/vnd.github+json`。

路径参数
名称、类型、描述
`owner` 字符串必填仓库的帐户所有者。名称不区分大小写。
`repo` 字符串必填不带 `.git` 扩展名的仓库名称。名称不区分大小写。

查询参数
名称、类型、描述
`per_page` 整数每页结果数（最大 100）。有关更多信息，请参阅“在 REST API 中使用分页”。默认值： `30`
`page` 整数要获取的结果的页码。有关更多信息，请参阅“在 REST API 中使用分页”。默认值： `1`

“列出环境”的 HTTP 响应状态代码

状态代码	描述
`200`	OK

“列出环境”的代码示例

请求示例

get/repos/{owner}/{repo}/environments

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/environments

响应

状态：200

{ "total_count": 1, "environments": [ { "id": 161088068, "node_id": "MDExOkVudmlyb25tZW50MTYxMDg4MDY4", "name": "staging", "url": "https://api.github.com/repos/github/hello-world/environments/staging", "html_url": "https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging", "created_at": "2020-11-23T22:00:40Z", "updated_at": "2020-11-23T22:00:40Z", "protection_rules": [ { "id": 3736, "node_id": "MDQ6R2F0ZTM3MzY=", "type": "wait_timer", "wait_timer": 30 }, { "id": 3755, "node_id": "MDQ6R2F0ZTM3NTU=", "prevent_self_review": false, "type": "required_reviewers", "reviewers": [ { "type": "User", "reviewer": { "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 } }, { "type": "Team", "reviewer": { "id": 1, "node_id": "MDQ6VGVhbTE=", "url": "https://api.github.com/teams/1", "html_url": "https://github.com/orgs/github/teams/justice-league", "name": "Justice League", "slug": "justice-league", "description": "A great team.", "privacy": "closed", "notification_setting": "notifications_enabled", "permission": "admin", "members_url": "https://api.github.com/teams/1/members{/member}", "repositories_url": "https://api.github.com/teams/1/repos", "parent": null } } ] }, { "id": 3756, "node_id": "MDQ6R2F0ZTM3NTY=", "type": "branch_policy" } ], "deployment_branch_policy": { "protected_branches": false, "custom_branch_policies": true } } ] }

获取环境

注意

若要获取有关分支必须匹配的名称模式（以便部署到此环境）的信息，请参阅“获取部署分支策略”。

任何具有仓库读取权限的用户都可以使用此端点。

OAuth 应用令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点与私有仓库。

用于“获取环境”的细粒度访问令牌

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

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

“操作”仓库权限（读取）

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

“获取环境”的参数

标头
名称、类型、描述
`accept` 字符串建议设置为 `application/vnd.github+json`。

路径参数
名称、类型、描述
`owner` 字符串必填仓库的帐户所有者。名称不区分大小写。
`repo` 字符串必填不带 `.git` 扩展名的仓库名称。名称不区分大小写。
`environment_name` 字符串必填环境的名称。名称必须进行 URL 编码。例如，名称中的任何斜杠都必须替换为 `%2F`。

“获取环境”的 HTTP 响应状态代码

状态代码	描述
`200`	OK

“获取环境”的代码示例

请求示例

get/repos/{owner}/{repo}/environments/{environment_name}

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/environments/ENVIRONMENT_NAME

响应

状态：200

{ "id": 161088068, "node_id": "MDExOkVudmlyb25tZW50MTYxMDg4MDY4", "name": "staging", "url": "https://api.github.com/repos/github/hello-world/environments/staging", "html_url": "https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging", "created_at": "2020-11-23T22:00:40Z", "updated_at": "2020-11-23T22:00:40Z", "protection_rules": [ { "id": 3736, "node_id": "MDQ6R2F0ZTM3MzY=", "type": "wait_timer", "wait_timer": 30 }, { "id": 3755, "node_id": "MDQ6R2F0ZTM3NTU=", "prevent_self_review": false, "type": "required_reviewers", "reviewers": [ { "type": "User", "reviewer": { "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 } }, { "type": "Team", "reviewer": { "id": 1, "node_id": "MDQ6VGVhbTE=", "url": "https://api.github.com/teams/1", "html_url": "https://github.com/orgs/github/teams/justice-league", "name": "Justice League", "slug": "justice-league", "description": "A great team.", "privacy": "closed", "notification_setting": "notifications_enabled", "permission": "admin", "members_url": "https://api.github.com/teams/1/members{/member}", "repositories_url": "https://api.github.com/teams/1/repos", "parent": null } } ] }, { "id": 3756, "node_id": "MDQ6R2F0ZTM3NTY=", "type": "branch_policy" } ], "deployment_branch_policy": { "protected_branches": false, "custom_branch_policies": true } }

创建或更新环境

创建或更新具有保护规则（例如必填审阅者）的环境。有关环境保护规则的更多信息，请参阅“环境”。

注意

若要创建或更新分支必须匹配的名称模式（以便部署到此环境），请参阅“部署分支策略”。

注意

要创建或更新环境的 Secrets，请参阅“GitHub Actions Secrets”。

OAuth 应用令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点。

用于“创建或更新环境”的细粒度访问令牌

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

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

“管理”存储库权限（写入）

“创建或更新环境”的参数

标头
名称、类型、描述
`accept` 字符串建议设置为 `application/vnd.github+json`。

路径参数
名称、类型、描述
`owner` 字符串必填仓库的帐户所有者。名称不区分大小写。
`repo` 字符串必填不带 `.git` 扩展名的仓库名称。名称不区分大小写。
`environment_name` 字符串必填环境的名称。名称必须进行 URL 编码。例如，名称中的任何斜杠都必须替换为 `%2F`。

名称、类型、描述

wait_timer 整数

作业在最初触发后延迟的时间。时间（以分钟为单位）必须是 0 到 43,200（30 天）之间的整数。

prevent_self_review 布尔值

是否阻止创建作业的用户批准自己的作业。

reviewers 对象数组或 null

可以审查引用环境的作业的人员或团队。您可以最多列出六个用户或团队作为审阅者。审阅者必须至少对存储库具有读取访问权限。只有其中一位必需的审阅者需要批准作业才能继续。

reviewers 的属性

名称、类型、描述
`type` 字符串审阅者的类型。可以是以下之一： `User`, `Team`
`id` 整数可以审查部署的用户或团队的 ID

deployment_branch_policy 对象或 null

此环境的部署分支策略类型。要允许所有分支部署，请设置为 null。

deployment_branch_policy 的属性

名称、类型、描述
`protected_branches` 布尔值必需是否只有具有分支保护规则的分支才能部署到此环境。如果 `protected_branches` 为 `true`，则 `custom_branch_policies` 必须为 `false`；如果 `protected_branches` 为 `false`，则 `custom_branch_policies` 必须为 `true`。
`custom_branch_policies` 布尔值必需是否只有与指定名称模式匹配的分支才能部署到此环境。如果 `custom_branch_policies` 为 `true`，则 `protected_branches` 必须为 `false`；如果 `custom_branch_policies` 为 `false`，则 `protected_branches` 必须为 `true`。

“创建或更新环境”的 HTTP 响应状态代码

状态代码	描述
`200`	OK
`422`	当环境名称无效或 `deployment_branch_policy` 中的 `protected_branches` 和 `custom_branch_policies` 设置为相同值时的验证错误

“创建或更新环境”的代码示例

请求示例

put/repos/{owner}/{repo}/environments/{environment_name}

curl -L \ -X PUT \ -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/environments/ENVIRONMENT_NAME \ -d '{"wait_timer":30,"prevent_self_review":false,"reviewers":[{"type":"User","id":1},{"type":"Team","id":1}],"deployment_branch_policy":{"protected_branches":false,"custom_branch_policies":true}}'

响应

状态：200

{ "id": 161088068, "node_id": "MDExOkVudmlyb25tZW50MTYxMDg4MDY4", "name": "staging", "url": "https://api.github.com/repos/github/hello-world/environments/staging", "html_url": "https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging", "created_at": "2020-11-23T22:00:40Z", "updated_at": "2020-11-23T22:00:40Z", "protection_rules": [ { "id": 3736, "node_id": "MDQ6R2F0ZTM3MzY=", "type": "wait_timer", "wait_timer": 30 }, { "id": 3755, "node_id": "MDQ6R2F0ZTM3NTU=", "prevent_self_review": false, "type": "required_reviewers", "reviewers": [ { "type": "User", "reviewer": { "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 } }, { "type": "Team", "reviewer": { "id": 1, "node_id": "MDQ6VGVhbTE=", "url": "https://api.github.com/teams/1", "html_url": "https://github.com/orgs/github/teams/justice-league", "name": "Justice League", "slug": "justice-league", "description": "A great team.", "privacy": "closed", "notification_setting": "notifications_enabled", "permission": "admin", "members_url": "https://api.github.com/teams/1/members{/member}", "repositories_url": "https://api.github.com/teams/1/repos", "parent": null } } ] }, { "id": 3756, "node_id": "MDQ6R2F0ZTM3NTY=", "type": "branch_policy" } ], "deployment_branch_policy": { "protected_branches": false, "custom_branch_policies": true } }

删除环境

OAuth 应用令牌和个人访问令牌（经典）需要 repo 范围才能使用此端点。

用于“删除环境”的细粒度访问令牌

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

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

“管理”存储库权限（写入）

“删除环境”的参数

标头
名称、类型、描述
`accept` 字符串建议设置为 `application/vnd.github+json`。

路径参数
名称、类型、描述
`owner` 字符串必填仓库的帐户所有者。名称不区分大小写。
`repo` 字符串必填不带 `.git` 扩展名的仓库名称。名称不区分大小写。
`environment_name` 字符串必填环境的名称。名称必须进行 URL 编码。例如，名称中的任何斜杠都必须替换为 `%2F`。

“删除环境”的 HTTP 响应状态代码

状态代码	描述
`204`	默认响应

“删除环境”的代码示例

请求示例

delete/repos/{owner}/{repo}/environments/{environment_name}

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/environments/ENVIRONMENT_NAME

默认响应

状态：204