Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

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

Use the REST API to manage custom deployment branch policies.

Informationen zu Richtlinien für Bereitstellungsbranches

Du kannst die REST-API verwenden, um benutzerdefinierte Namensmuster anzugeben, mit denen Branches übereinstimmen müssen, damit die Bereitstellung in einer Umgebung funktioniert. Die deployment_branch_policy.custom_branch_policies-Eigenschaft für die Umgebung muss auf true festgelegt werden, um diese Endpunkte zu verwenden. Zum Aktualisieren der deployment_branch_policy für eine Umgebung findest du unter Erstellen oder Aktualisieren einer Umgebung.

Weitere Informationen zum Einschränken von Umgebungsbereitstellungen auf bestimmte Branches findest du unter Verwenden von Umgebungen für die Bereitstellung.

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
acceptstring

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

Path parameters
Name, Type, Description
ownerstringRequired

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

repostringRequired

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

environment_namestringRequired

The name of the environment.

Query parameters
Name, Type, Description
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP response status codes for "List deployment branch policies"

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

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

Path parameters
Name, Type, Description
ownerstringRequired

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

repostringRequired

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

environment_namestringRequired

The name of the environment.

Body parameters
Name, Type, Description
namestringRequired

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

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

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 actions:read permission to use this endpoint.

Parameters for "Get a deployment branch policy"

Headers
Name, Type, Description
acceptstring

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

Path parameters
Name, Type, Description
ownerstringRequired

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

repostringRequired

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

environment_namestringRequired

The name of the environment.

branch_policy_idintegerRequired

The unique identifier of the branch policy.

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

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

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

Path parameters
Name, Type, Description
ownerstringRequired

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

repostringRequired

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

environment_namestringRequired

The name of the environment.

branch_policy_idintegerRequired

The unique identifier of the branch policy.

Body parameters
Name, Type, Description
namestringRequired

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

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

Path parameters
Name, Type, Description
ownerstringRequired

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

repostringRequired

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

environment_namestringRequired

The name of the environment.

branch_policy_idintegerRequired

The unique identifier of the branch policy.

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

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