Skip to main content

This version of GitHub Enterprise Server will be discontinued on 2024-08-29. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

The REST API is now versioned. For more information, see "About API versioning."

REST API endpoints for deployment environments

Use the REST API to create, configure, and delete deployment environments.

About deployment environments

For more information about environments, see "Using environments for deployment." To manage environment secrets, see "REST API endpoints for GitHub Actions Secrets."

Environments, environment secrets, and deployment protection rules are available in public repositories for all current GitHub plans. They are not available on legacy plans, such as Bronze, Silver, or Gold. For access to environments, environment secrets, and deployment branches in private or internal repositories, you must use GitHub Pro, GitHub Team, or GitHub Enterprise.

List environments

Lists the environments for a repository.

Anyone with read access to the repository can use this endpoint.

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

Fine-grained access tokens for "List environments"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Actions" repository permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "List environments"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
owner string Required

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

repo string Required

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

Query parameters
Name, Type, Description
per_page integer

The number of results per page (max 100). For more information, see "Using pagination in the REST API."

Default: 30

page integer

The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Default: 1

HTTP response status codes for "List environments"

Status codeDescription
200

OK

Code samples for "List environments"

Request example

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" \ 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://HOSTNAME/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://HOSTNAME/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://HOSTNAME/users/octocat/followers", "following_url": "https://HOSTNAME/users/octocat/following{/other_user}", "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}", "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions", "organizations_url": "https://HOSTNAME/users/octocat/orgs", "repos_url": "https://HOSTNAME/users/octocat/repos", "events_url": "https://HOSTNAME/users/octocat/events{/privacy}", "received_events_url": "https://HOSTNAME/users/octocat/received_events", "type": "User", "site_admin": false } }, { "type": "Team", "reviewer": { "id": 1, "node_id": "MDQ6VGVhbTE=", "url": "https://HOSTNAME/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://HOSTNAME/teams/1/members{/member}", "repositories_url": "https://HOSTNAME/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

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.

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

Fine-grained access tokens for "Get an environment"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Actions" repository permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "Get an environment"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
owner string Required

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

repo string Required

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

environment_name string Required

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

HTTP response status codes for "Get an environment"

Status codeDescription
200

OK

Code samples for "Get an environment"

Request example

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" \ http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/environments/ENVIRONMENT_NAME

Response

Status: 200
{ "id": 161088068, "node_id": "MDExOkVudmlyb25tZW50MTYxMDg4MDY4", "name": "staging", "url": "https://HOSTNAME/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://HOSTNAME/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://HOSTNAME/users/octocat/followers", "following_url": "https://HOSTNAME/users/octocat/following{/other_user}", "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}", "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions", "organizations_url": "https://HOSTNAME/users/octocat/orgs", "repos_url": "https://HOSTNAME/users/octocat/repos", "events_url": "https://HOSTNAME/users/octocat/events{/privacy}", "received_events_url": "https://HOSTNAME/users/octocat/received_events", "type": "User", "site_admin": false } }, { "type": "Team", "reviewer": { "id": 1, "node_id": "MDQ6VGVhbTE=", "url": "https://HOSTNAME/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://HOSTNAME/teams/1/members{/member}", "repositories_url": "https://HOSTNAME/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

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.

Fine-grained access tokens for "Create or update an environment"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Administration" repository permissions (write)

Parameters for "Create or update an environment"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
owner string Required

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

repo string Required

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

environment_name string Required

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

Body parameters
Name, Type, Description
wait_timer integer

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

reviewers array 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.

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_policy object or null

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

Name, Type, Description
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.

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.

HTTP response status codes for "Create or update an environment"

Status codeDescription
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

Code samples for "Create or update an environment"

Request example

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" \ 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://HOSTNAME/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://HOSTNAME/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://HOSTNAME/users/octocat/followers", "following_url": "https://HOSTNAME/users/octocat/following{/other_user}", "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}", "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions", "organizations_url": "https://HOSTNAME/users/octocat/orgs", "repos_url": "https://HOSTNAME/users/octocat/repos", "events_url": "https://HOSTNAME/users/octocat/events{/privacy}", "received_events_url": "https://HOSTNAME/users/octocat/received_events", "type": "User", "site_admin": false } }, { "type": "Team", "reviewer": { "id": 1, "node_id": "MDQ6VGVhbTE=", "url": "https://HOSTNAME/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://HOSTNAME/teams/1/members{/member}", "repositories_url": "https://HOSTNAME/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

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

Fine-grained access tokens for "Delete an environment"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Administration" repository permissions (write)

Parameters for "Delete an environment"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
owner string Required

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

repo string Required

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

environment_name string Required

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

HTTP response status codes for "Delete an environment"

Status codeDescription
204

Default response

Code samples for "Delete an environment"

Request example

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" \ http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/environments/ENVIRONMENT_NAME

Default response

Status: 204