Deployment branch policies

Use the REST API to manage custom deployment branch policies.

About deployment branch policies

You can use the REST API to specify custom name patterns that branches must match in order to deploy to an environment. The deployment_branch_policy.custom_branch_policies property for the environment must be set to true to use these endpoints. To update the deployment_branch_policy for an environment, see "Deployment environments."

For more information about restricting environment deployments to certain branches, see "Using environments for deployment."

List deployment branch policies

Works with GitHub Apps

Lists the deployment branch policies for an environment.

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 deployment branch policies"

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

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 deployment branch policies"

Status code	Description
`200`	OK

Code samples for "List deployment branch policies"

get/repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/environments/ENVIRONMENT_NAME/deployment-branch-policies

Response

Status: 200

{
  "total_count": 2,
  "branch_policies": [
    {
      "id": 361471,
      "node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjE0NzE=",
      "name": "release/*"
    },
    {
      "id": 361472,
      "node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjE0NzI=",
      "name": "main"
    }
  ]
}

Create a deployment branch policy

Works with GitHub Apps

Creates a deployment branch policy for an environment.

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 a deployment branch policy"

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
`name` string Required The name pattern that branches or tags must match in order to deploy to the environment. Wildcard characters will not match `/`. For example, to match branches that begin with `release/` and contain an additional single slash, use `release//`. For more information about pattern matching syntax, see the Ruby File.fnmatch documentation.

HTTP response status codes for "Create a deployment branch policy"

Status code	Description
`200`	OK
`303`	Response if the same branch name pattern already exists
`404`	Not Found or `deployment_branch_policy.custom_branch_policies` property for the environment is set to false

Code samples for "Create a deployment branch policy"

Select the example type

post/repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/environments/ENVIRONMENT_NAME/deployment-branch-policies \
  -d '{"name":"release/*"}'

Response

Status: 200

{
  "id": 364662,
  "node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjQ2NjI=",
  "name": "release/*"
}

Get a deployment branch policy

Works with GitHub Apps

Gets a deployment branch policy for an environment.

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 administration:read permission for the repository to use this endpoint.

Parameters for "Get a deployment branch policy"

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`.
`branch_policy_id` integer Required The unique identifier of the branch policy.

HTTP response status codes for "Get a deployment branch policy"

Status code	Description
`200`	OK

Code samples for "Get a deployment branch policy"

get/repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies/{branch_policy_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/environments/ENVIRONMENT_NAME/deployment-branch-policies/BRANCH_POLICY_ID

Response

Status: 200

{
  "id": 364662,
  "node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjQ2NjI=",
  "name": "release/*"
}

Update a deployment branch policy

Works with GitHub Apps

Updates a deployment branch policy for an environment.

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 "Update a deployment branch policy"

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`.
`branch_policy_id` integer Required The unique identifier of the branch policy.

Body parameters
Name, Type, Description
`name` string Required The name pattern that branches must match in order to deploy to the environment. Wildcard characters will not match `/`. For example, to match branches that begin with `release/` and contain an additional single slash, use `release//`. For more information about pattern matching syntax, see the Ruby File.fnmatch documentation.

HTTP response status codes for "Update a deployment branch policy"

Status code	Description
`200`	OK

Code samples for "Update a deployment branch policy"

put/repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies/{branch_policy_id}

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/deployment-branch-policies/BRANCH_POLICY_ID \
  -d '{"name":"release/*"}'

Response

Status: 200

{
  "id": 364662,
  "node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjQ2NjI=",
  "name": "release/*"
}

Delete a deployment branch policy

Works with GitHub Apps

Deletes a deployment branch policy for an environment.

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 "Delete a deployment branch policy"

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`.
`branch_policy_id` integer Required The unique identifier of the branch policy.

HTTP response status codes for "Delete a deployment branch policy"

Status code	Description
`204`	No Content

Code samples for "Delete a deployment branch policy"

delete/repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies/{branch_policy_id}

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/deployment-branch-policies/BRANCH_POLICY_ID

Response

Status: 204