Skip to content
forgit api docs

Create or update an environment

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

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 “GitHub Actions secrets.”

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
owner
required
string

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

repo
required
string

The name of the repository without the .git extension. The name is not case sensitive.

environment_name
required
string

The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with %2F.

Request Body

Section titled “ Request Body ”
Media type application/json
object
wait_timer

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

integer
prevent_self_review

Whether or not a user who created the job is prevented from approving their own job.

boolean
reviewers

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.

Array<object>
nullable
object
type

The type of reviewer.

string
Allowed values: User Team
id

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

integer
deployment_branch_policy

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

object
protected_branches
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.

boolean
custom_branch_policies
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.

boolean
Examples
Example default 
{
  "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
  }
}

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Response

Media type application/json
Environment

Details of a deployment environment

object
id
required

The id of the environment.

integer format: int64
node_id
required
string
name
required

The name of the environment.

string
url
required
string
html_url
required
string
created_at
required

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

string format: date-time
updated_at
required

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

string format: date-time
protection_rules

Built-in deployment protection rules for the environment.

Array
Any of:
object
id
required
integer
node_id
required
string
type
required
string
wait_timer

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

integer
deployment_branch_policy

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

object
protected_branches
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.

boolean
custom_branch_policies
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.

boolean
Examples
Example default 
{
  "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
  }
}

422

Section titled “ 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

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}