Create or update an environment - GitHub v3 REST API

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.

curl --location --request PUT 'https://api.github.com/repos///environments/' \ --header 'Content-Type: application/json' \ --data-raw '{ "deployment_branch_policy": { "custom_branch_policies": true, "protected_branches": false }, "reviewers": [ { "id": 1, "type": "User" }, { "id": 1, "type": "Team" } ], "wait_timer": 30 }'

{ "created_at": "2020-11-23T22:00:40.000Z", "deployment_branch_policy": { "custom_branch_policies": true, "protected_branches": true }, "html_url": "https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging", "id": 56780428, "name": "staging", "node_id": "MDExOkVudmlyb25tZW50NTY3ODA0Mjg=", "protection_rules": [ { "id": 3515, "node_id": "MDQ6R2F0ZTM1MTU=", "type": "wait_timer", "wait_timer": 30 } ], "updated_at": "2020-11-23T22:00:40.000Z", "url": "https://api.github.com/repos/github/hello-world/environments/staging" }

Request

Path Params

owner

string

required

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

repo

string

required

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

environment_name

string

required

The name of the environment.

Body Params application/json

object | null

optional

deployment_branch_policy

object (deployment-branch-policy-settings) | null

optional

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

custom_branch_policies

boolean

required

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.

protected_branches

boolean

required

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.

reviewers

array [object {2}] | null

optional

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.

integer

optional

The id of the user or team who can review the deployment

Example:

4532992

type

enum<string>

optional

The type of reviewer.

Allowed values:

UserTeam

Example:

User

wait_timer

integer

optional

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).

Example:

Examples

Responses

🟢200Response

application/json

Body

Details of a deployment environment

created_at

string <date-time>

required

The time that the environment was created, in ISO 8601 format.

Example:

2020-11-23T22:00:40.000Z

deployment_branch_policy

object (deployment-branch-policy-settings) | null

optional

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

custom_branch_policies

boolean

required

protected_branches

boolean

required

html_url

string

required

Example:

https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging

integer

required

The id of the environment.

Example:

56780428

name

string

required

The name of the environment.

Example:

staging

node_id

string

required

Example:

MDExOkVudmlyb25tZW50NTY3ODA0Mjg=

protection_rules

array [anyOf]

optional

object

optional

object

optional

object

optional

updated_at

string <date-time>

required

The time that the environment was last updated, in ISO 8601 format.

Example:

2020-11-23T22:00:40.000Z

url

string

required

Example:

https://api.github.com/repos/github/hello-world/environments/staging

🟠422Validation 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