部署环境

部署环境 API 支持创建、配置和� 除部署环境。

关于部署环境 API

有关环境的详细信息，请参阅“使用环境进行部署”。若要管理环境机密，请参阅“机密”。

所有产品的公共存储库提供环境、环境机密和环境保护规则。要访问专用存储库或内部存储库中的环境、环境机密和部署分支，必须使用 GitHub Pro、GitHub Team 或 GitHub Enterprise 。要访问专用存储库或内部存储库中的其他环境保护规则，必须使用 GitHub Enterprise 。

List environments

使用 GitHub Apps

Lists the environments for a repository.

Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository. The name is not case sensitive.
Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). Default: `30`
`page`integer Page number of the results to fetch. Default: `1`

HTTP 响应状态代� �

状态代� �	说明
`200`	OK

代� �示例

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

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/environments

Response

Status: 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=",
          "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",
                "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
      }
    }
  ]
}

Get an environment

使用 GitHub Apps

Note: To get information about name patterns that branches must match in order to deploy to this environment, see "Get a deployment branch policy."

Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository. The name is not case sensitive.
`environment_name`stringRequired The name of the environment.

HTTP 响应状态代� �

状态代� �	说明
`200`	OK

代� �示例

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

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/environments/ENVIRONMENT_NAME

Response

Status: 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=",
      "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",
            "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
  }
}

Create or update an environment

使用 GitHub Apps

Create or update an environment with protection rules, such as required reviewers. For more information about environment protection rules, see "Environments."

Note: To create or update name patterns that branches must match in order to deploy to this environment, see "Deployment branch policies."

Note: To create or update secrets for an environment, see "Secrets."

You must authenticate using an access token with the repo scope to use this endpoint. GitHub Apps must have the administration:write permission for the repository to use this endpoint.

参数

Headers

Name, Type, Description

acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters

Name, Type, Description

ownerstringRequired

The account owner of the repository. The name is not case sensitive.

repostringRequired

The name of the repository. The name is not case sensitive.

environment_namestringRequired

The name of the environment.

Body parameters

Name, Type, Description

wait_timerinteger

The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).

reviewersarray of objects or null

The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.

Properties of reviewers

Name, Type, Description
`type`string The type of reviewer. Can be one of: `User`, `Team`
`id`integer The id of the user or team who can review the deployment

deployment_branch_policyobject or null

The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.

Properties of deployment_branch_policy

Name, Type, Description
`protected_branches`booleanRequired Whether only branches with branch protection rules can deploy to this environment. If `protected_branches` is `true`, `custom_branch_policies` must be `false`; if `protected_branches` is `false`, `custom_branch_policies` must be `true`.
`custom_branch_policies`booleanRequired Whether only branches that match the specified name patterns can deploy to this environment. If `custom_branch_policies` is `true`, `protected_branches` must be `false`; if `custom_branch_policies` is `false`, `protected_branches` must be `true`.

HTTP 响应状态代� �

状态代� �	说明
`200`	OK
`422`	Validation error when the environment name is invalid or when `protected_branches` and `custom_branch_policies` in `deployment_branch_policy` are set to the same value

代� �示例

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

curl \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/environments/ENVIRONMENT_NAME \
  -d '{"wait_timer":30,"reviewers":[{"type":"User","id":1},{"type":"Team","id":1}],"deployment_branch_policy":{"protected_branches":false,"custom_branch_policies":true}}'

Response

Status: 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=",
      "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",
            "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
  }
}

Delete an environment

使用 GitHub Apps

You must authenticate using an access token with the repo scope to use this endpoint.

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository. The name is not case sensitive.
`environment_name`stringRequired The name of the environment.

HTTP 响应状态代� �

状态代� �	说明
`204`	Default response

代� �示例

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

curl \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/environments/ENVIRONMENT_NAME

Default response

Status: 204