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 "Actions."

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

Works with 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.

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). Default: `30`
`page` integer Page number of the results to fetch. Default: `1`

HTTP response status codes for "List environments"

Status code	Description
`200`	OK

Code samples for "List environments"

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

curl -L \
  -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://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

Works with 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.

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 code	Description
`200`	OK

Code samples for "Get an environment"

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

curl -L \
  -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://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

Works with 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 "GitHub Actions 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 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`.

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.

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_policy object 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` 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 code	Description
`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"

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

curl -L \
  -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://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

Works with GitHub Apps

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

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 code	Description
`204`	Default response

Code samples for "Delete an environment"

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

curl -L \
  -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