This version of GitHub Enterprise was discontinued on 2023-01-18. 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. For help with the upgrade, contact GitHub Enterprise support.
We've recently moved some of the REST API documentation. If you can't find what you're looking for, you might try the new Branches, Collaborators, Commits, Deploy Keys, Deployments, GitHub Pages, Releases, Metrics, Webhooks REST API pages.
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 "Secrets."
Environments, environment secrets, and environment protection rules are available in public repositories for all products. For access to environments, environment secrets, and deployment branches in private or internal repositories, you must use GitHub Pro, GitHub Team, or GitHub Enterprise. For access to other environment protection rules in private or internal repositories, you must use GitHub Enterprise.
List environments
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.
Parameters
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
owner stringRequiredThe account owner of the repository. The name is not case sensitive. |
repo stringRequiredThe name of the repository. The name is not case sensitive. |
Query parameters |
Name, Type, Description |
per_page integerThe number of results per page (max 100). Default: |
page integerPage number of the results to fetch. Default: |
HTTP response status codes
Status code | Description |
---|---|
200 | OK |
Code samples
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
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.
Parameters
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
owner stringRequiredThe account owner of the repository. The name is not case sensitive. |
repo stringRequiredThe name of the repository. The name is not case sensitive. |
environment_name stringRequiredThe name of the environment. |
HTTP response status codes
Status code | Description |
---|---|
200 | OK |
Code samples
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
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.
Parameters
Headers | ||||||
---|---|---|---|---|---|---|
Name, Type, Description | ||||||
accept stringSetting to | ||||||
Path parameters | ||||||
Name, Type, Description | ||||||
owner stringRequiredThe account owner of the repository. The name is not case sensitive. | ||||||
repo stringRequiredThe name of the repository. The name is not case sensitive. | ||||||
environment_name stringRequiredThe name of the environment. | ||||||
Body parameters | ||||||
Name, Type, Description | ||||||
wait_timer integerThe 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 nullThe 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 |
Name, Type, Description |
---|
type stringThe type of reviewer. Can be one of: |
id integerThe id of the user or team who can review the deployment |
deployment_branch_policy
object or nullThe 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 booleanRequiredWhether only branches with branch protection rules can deploy to this environment. If |
custom_branch_policies booleanRequiredWhether only branches that match the specified name patterns can deploy to this environment. If |
HTTP response status codes
Status code | Description |
---|---|
200 | OK |
422 | Validation error when the environment name is invalid or when |
Code samples
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
You must authenticate using an access token with the repo scope to use this endpoint.
Parameters
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
owner stringRequiredThe account owner of the repository. The name is not case sensitive. |
repo stringRequiredThe name of the repository. The name is not case sensitive. |
environment_name stringRequiredThe name of the environment. |
HTTP response status codes
Status code | Description |
---|---|
204 | Default response |
Code samples
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