How to create/edit branch restrictions in Bitbucket Cloud repositories via API
Platform Notice: Cloud Only - This article only applies to Atlassian products on the cloud platform.
Summary
This document contains example curl commands to create and update branch permissions via API. API endpoints used in this document are listed here - Branch restrictions API
1
2
3
4
5
GET /repositories/{workspace}/{repo_slug}/branch-restrictions
POST /repositories/{workspace}/{repo_slug}/branch-restrictions
GET /repositories/{workspace}/{repo_slug}/branch-restrictions/{id}
PUT /repositories/{workspace}/{repo_slug}/branch-restrictions/{id}
DEL /repositories/{workspace}/{repo_slug}/branch-restrictions/{id}Solution
Before we dive into the examples, let's look at some important information such as authentication, UUIDs of the users, and forming the right API URL.
Authentication: We support various authentication methods. Please refer to our Authentication methods document and select as per your preference and use case. We have used app password in all the examples on this page.
URL: The API URL referenced in the below examples contains various details such as WorkspaceID, and repoSlug. When you access a repository in the browser, the format would look like https://bitbucket.org/myexampleworkspace/myrepo/. In this case, WorkspaceID is myexampleworkspace and repoSlug is myrepo.
UUID: In most of the examples below, we have referenced the "UUID" of the user, This value can be obtained from the workspace members' API
Example 1: Create a simple branch permission that provides permission to users to "Merge via pull requests" on feature branches
1
2
3
4
5
6
7
8
9
10
curl -u <username>:<apppasssword> --request POST \
--url 'https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions' \
--header 'Content-Type: application/json' \
--data '{ "pattern": "feature/*",
"kind": "restrict_merges",
"users": [
{ "uuid": "{<UUID of th user1 here>}"},
{ "uuid": "{<UUID of th user2 here>}"}
]
}'Example 2: Create a simple branch permission that provides permission to users to "push" directly to release branches
1
2
3
4
5
6
7
8
9
10
curl -u <username>:<apppasssword> --request POST \
--url 'https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions' \
--header 'Content-Type: application/json' \
--data '{ "pattern": "release/*",
"kind": "push",
"users": [
{ "uuid": "{<UUID of th user1 here>}"},
{ "uuid": "{<UUID of th user2 here>}"}
]
}'Example 2a: For the kind value "push", if the users' list in the above command is empty, the direct write/push access is restricted to everybody. Below is an example
1
2
3
4
5
6
7
curl -u <username>:<apppasssword> --request POST \
--url 'https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions' \
--header 'Content-Type: application/json' \
--data '{ "pattern": "release/*",
"kind": "push",
"users": []
}'Example 3: Create a branch permission rule to set the "Minimum number of approvals" for a PR to be merged
kind attribute for this merge check would be"require_approvals_to_merge"
value attribute indicates the number of minimum approvals required for the PR to be allowed to be merged
1
2
3
4
5
6
7
curl -u <username>:<apppasssword> --request POST \
--url 'https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions' \
--header 'Content-Type: application/json' \
--data '{ "pattern": "feature/*",
"kind": "require_approvals_to_merge",
"value": 2
}'The curl command would look similar for the below 3 merge checks as well. On the right-hand side is the description of the merge check followed by its corresponding kind value.
Minimum number of approvals from default reviewers - require_default_reviewer_approvals_to_merge
Minimum number of successful builds for the last commit with no failed builds and no in progress builds - require_passing_builds_to_merge
Maximum number of commits behind destination branch - require_commits_behind
Example 4: Create a branch permission rule to enable "Reset requested changes when the source branch is modified"
kind attribute for this merge check would be"reset_pullrequest_changes_requested_on_change"
1
2
3
4
5
6
curl -u <username>:<apppasssword> --request POST \
--url 'https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions' \
--header 'Content-Type: application/json' \
--data '{ "pattern": "feature/*",
"kind": "reset_pullrequest_changes_requested_on_change"
}'The curl command to enable the below merge checks would be similar except for the value of kind. Below is the list of merge checks and their associated kind values for your reference.
Allow automatic merge when builds pass -allow_auto_merge_when_builds_pass
No unresolved pull request tasks -require_tasks_to_be_completed
No changes are requested -require_no_changes_requested
Reset approvals when the source branch is modified -reset_pullrequest_approvals_on_change
Prevent a merge with unresolved merge checks - enforce_merge_checks
Allow rewriting branch history -force
Allow deleting this branch -delete
Example 5: Update a branch permission rule to modify the users that have "Merge via pull requests" permission on feature branches
There are two steps involved in order to update an existing branch restriction rule each of which is explained in detail below.
Get the ID of the existing branch restriction rule
1
2
curl -u <username>:<apppasssword> --request GET \
--url 'https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions'Sample output of the above GET request,
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
"values": [
{
"id": 41745873,
"kind": "require_approvals_to_merge",
"value": 1,
"branch_match_kind": "glob",
"type": "branchrestriction",
"users": [],
"pattern": "master",
"groups": [],
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions/41745873"
}
}
},
{
"id": 41745872,
"kind": "delete",
"value": null,
"branch_match_kind": "glob",
"type": "branchrestriction",
"users": [],
"pattern": "master",
"groups": [],
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions/41745872"
}
}
},
{
"id": 41745871,
"kind": "force",
"value": null,
"branch_match_kind": "glob",
"type": "branchrestriction",
"users": [],
"pattern": "master",
"groups": [],
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions/41745871"
}
}
},
{
"id": 41745443,
"kind": "restrict_merges",
"value": null,
"branch_match_kind": "glob",
"type": "branchrestriction",
"users": [
{
"display_name": "<some user>",
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/users/%7B<UUID here>%7D"
},
"avatar": {
"href": "https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/BK-6.png"
},
"html": {
"href": "https://bitbucket.org/%7B<UUID here>%7D/"
}
},
"type": "user",
"uuid": "{<UUID here>}",
"account_id": "<AID here>",
"nickname": "<some name>"
}
],
"pattern": "feature/*",
"groups": [],
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions/41745443"
}
}
}
],
"pagelen": 10,
"size": 4,
"page": 1
}
As we want to modify the users that have permission to merge via pull request, the kindwe should be looking at from the above JSON response is "restrict_merges". And the ID in this exampleis 41745443. Below is a sample PUT request,
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl -u <username>:<apppassword> --request PUT \
--url 'https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions/41745443' \
--header 'Content-Type: application/json' \
--data '{
"kind": "restrict_merges",
"users": [
{
"uuid": "{<new user UUID here>}"
}
],
"groups": [
{"slug": "read-only"},
{"slug": "developers"}
]
}'In this PUT request, we modified the user and added two user groups that have permission to merge via pull request. In this example, read-only and developers are the group slugs.
Example 6: Delete a branch permission rule
There are two steps involved in order to delete a branch restriction rule similar to example 4. The first step is to get the ID of the rule we would like to delete and then send a DELETE request as shown in the below query.
1
2
curl -u <username>:<apppassword> --request DELETE \
--url 'https://api.bitbucket.org/2.0/repositories/<WorkspaceID>/<repoSlug>/branch-restrictions/41745982' Was this helpful?