Configure branch restrictions
Learn how to use the Repository Settings API to configure branch restrictions.
All sample requests in this guide include the following path parameters:
Parameter name | Description |
---|---|
tenantId | Your tenant ID. |
starSystemId | ID of a star system that includes the repository for which you configure the branch restrictions. |
repositoryName | Name of a repository. See supported repositories. |
About branch restrictions
By configuring branch restrictions, you can control who can interact with your branches and what actions they can perform.
Prerequisities
The following limitations apply:
- You can't modify the
NO_DELETION
restriction for themaster
anddevelop
branches. - You can't modify any restrictions for the
gw-releases
branch. - You can't modify restrictions configured on a star system level.
- The branch restrictions don't apply to Guidewire.
Default configuration
Branch | Introduce changes | Delete branch | Rewrite history | Push and merge directly |
---|---|---|---|---|
master | Everyone | Nobody | – Guidewire
| – Guidewire
|
develop | – Guidewire
| Nobody | – Guidewire
| – Guidewire
|
gw-releases | Guidewire | Nobody | Guidewire | Guidewire |
hotfix-* | – Guidewire
| Everyone | – Guidewire
| – Guidewire
|
Custom branches | Everyone | Everyone | Everyone | Everyone |
For details on supported roles, see Source code in Cloud Platform documentation.
Definition
{
"id": "5",
"scope": {
"type": "REPOSITORY"
},
"type": "NO_DIRECT_CHANGES",
"matcher": {
"key": "master",
"type": "BRANCH",
"active": true
},
"excludedUsers": [
{
"name": "johndoe@example.com",
"displayName": "John Doe",
"active": true
}
],
"excludedGroups": []
}
ID and scope
Restriction ID is generated automatically and is unique at a tenant level.
Each restriction has also a specific scope. The scope
parameter has one of the following values:
PROJECT
indicates that a restriction is inherited and defined at the star system level.REPOSITORY
indicates a custom restriction. Every restriction that you create using the Repository Settings API has this scope.
Restrictions
The following restrictions are available:
Type | Description |
---|---|
NO_REWRITING_HISTORY | Restrict rewriting the branch history. |
NO_DELETION | Restrict deleting the branch. |
NO_DIRECT_CHANGES | Restrict pushing and merging directly into the branch. |
NO_CHANGES | Restrict introducing changes to the branch. |
Branches
You can apply a restrictions to one specific branch or to multiple branches.
To define a branch, use the type
and key
parameters:
Type | Key | Description |
---|---|---|
BRANCH | {branchName} | Applies to the branch with the specified name. |
PATTERN | Accepted wild cards: ? , * , ** | Applies to every branch whose name matches the pattern. For details, see Branch patterns. |
Excluded users and groups
You can define users and user groups to whom a branch restriction doesn't apply. As a result, you can create configurations where only specific people can perform certain actions.
Example
To ensure code quality, you can decide that only a tech lead is allowed to push and merge directly into the master
branch. In such scenario, do the following:
- Configure the
NO_DIRECT_CHANGES
restriction on themaster
branch. - Specify the tech lead as the only excluded user.
To define an excluded user, provide their username. In most cases, it's the same as their email address. The user must have a Bitbucket account and access rights to the star system that includes the repository.
Get configuration
To retrieve a list of all branch restrictions configured for a repository, send the following GET
request:
curl -X 'GET' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/branch-permissions' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access_token}'
Response contains a JSON object with all the restrictions currently configured for this repository.
{
"id": "1",
"scope": {
"type": "REPOSITORY"
},
"type": "NO_DELETION",
"matcher": {
"key": "refs/heads/hotflix-*",
"type": "PATTERN",
"active": true
},
"excludedUsers": [
{
"name": "johndoe@example.com",
"displayName": "John Doe",
"active": true
}
],
"excludedGroups": []
}
Create restriction
To create a restriction, send the following POST
request:
curl -X 'POST' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/branch-permissions' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access_token}'
-H 'Content-Type: application/json' \
-d '{body}'
Where body
defines the restriction.
For example, to restrict everyone from rewriting history of a develop
branch, use the following:
{
"type": "NO_REWRITING_HISTORY",
"matcher": {
"key": "develop",
"type": "BRANCH"
}
}
For a successful request, you will receive the 200
status code and the created restriction with its ID and scope.
{
"id": "6",
"scope": {
"type": "REPOSITORY"
},
"type": "NO_REWRITING_HISTORY",
"matcher": {
"key": "develop",
"type": "BRANCH",
"active": true
},
"excludedUsers": [],
"excludedGroups": []
}
Update restriction
To update an already configured restriction, send the following PUT
request:
curl -X 'PUT' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/branch-permissions/{branchPermissionId}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{body}'
Where:
{branchPermissionId}
is an ID of the restriction you want to update.{body}
contains the updated restriction.
For example, to update the restriction created in the previous step by adding John Doe to excluded users, use the following:
{
"type": "NO_REWRITING_HISTORY",
"matcher": {
"key": "develop",
"type": "BRANCH"
},
"excludedUsers": ["johndoe@example.com"]
}
For a successful request, you will receive the 200
status code and the updated restriction.
{
"id": "6",
"scope": {
"type": "REPOSITORY"
},
"type": "NO_REWRITING_HISTORY",
"matcher": {
"key": "develop",
"type": "BRANCH",
"active": true
},
"excludedUsers": ["johndoe@example.com"],
"excludedGroups": []
}
Delete restriction
By deleting a branch restriction, you restore the default configuration. To delete a restriction, send the following DELETE
request:
curl -X 'DELETE' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/branch-permissions/{branchPermissionId}' \
-H 'Accept: */*' \
-H 'Authorization: Bearer {access_token}'
Where {branchPermissionId}
is an ID of the restriction you want to delete.
For a successful request, you will receive the 204
status code.
Was this page helpful?