This version of GitHub Enterprise Server was discontinued on 2024-07-09. 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.
REST API endpoints for 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 "REST API endpoints for deployment environments."
For more information about restricting environment deployments to certain branches, see "Using environments for deployment."
List deployment branch policies
Lists the deployment branch policies for an environment.
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.
Parameters for "List deployment branch policies"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
owner string RequiredThe account owner of the repository. The name is not case sensitive. |
repo string RequiredThe name of the repository without the |
environment_name string RequiredThe name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
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: |
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: |
HTTP response status codes for "List deployment branch policies"
Status code | Description |
---|---|
200 | OK |
Code samples for "List deployment branch policies"
Request example
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/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
Creates a deployment branch policy for an environment.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
Parameters for "Create a deployment branch policy"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
owner string RequiredThe account owner of the repository. The name is not case sensitive. |
repo string RequiredThe name of the repository without the |
environment_name string RequiredThe name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
Name, Type, Description |
---|
name string RequiredThe name pattern that branches or tags must match in order to deploy to the environment. Wildcard characters will not match |
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 |
Code samples for "Create a deployment branch policy"
Request examples
curl -L \
-X POST \
-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/deployment-branch-policies \
-d '{"name":"release/*"}'
Response
Status: 200
{
"id": 364662,
"node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjQ2NjI=",
"name": "release/*"
}
Get a deployment branch policy
Gets a deployment branch policy for an environment.
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.
Parameters for "Get a deployment branch policy"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
owner string RequiredThe account owner of the repository. The name is not case sensitive. |
repo string RequiredThe name of the repository without the |
environment_name string RequiredThe name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
branch_policy_id integer RequiredThe 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"
Request example
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/deployment-branch-policies/BRANCH_POLICY_ID
Response
Status: 200
{
"id": 364662,
"node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjQ2NjI=",
"name": "release/*"
}
Update a deployment branch policy
Updates a deployment branch policy for an environment.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
Parameters for "Update a deployment branch policy"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
owner string RequiredThe account owner of the repository. The name is not case sensitive. |
repo string RequiredThe name of the repository without the |
environment_name string RequiredThe name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
branch_policy_id integer RequiredThe unique identifier of the branch policy. |
Name, Type, Description |
---|
name string RequiredThe name pattern that branches must match in order to deploy to the environment. Wildcard characters will not match |
HTTP response status codes for "Update a deployment branch policy"
Status code | Description |
---|---|
200 | OK |
Code samples for "Update a deployment branch policy"
Request example
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/deployment-branch-policies/BRANCH_POLICY_ID \
-d '{"name":"release/*"}'
Response
Status: 200
{
"id": 364662,
"node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjQ2NjI=",
"name": "release/*"
}
Delete a deployment branch policy
Deletes a deployment branch policy for an environment.
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
Parameters for "Delete a deployment branch policy"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
owner string RequiredThe account owner of the repository. The name is not case sensitive. |
repo string RequiredThe name of the repository without the |
environment_name string RequiredThe name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with |
branch_policy_id integer RequiredThe 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"
Request example
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/deployment-branch-policies/BRANCH_POLICY_ID
Response
Status: 204