Skip to main content

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 nameDescription
tenantIdYour tenant ID.
starSystemIdID of a star system that includes the repository for which you configure the branch restrictions.
repositoryNameName 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 the master and develop 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

BranchIntroduce changesDelete branchRewrite historyPush and merge directly
masterEveryoneNobody

– Guidewire
– Admin

– Guidewire
– Admin

develop

– Guidewire
– Admin

Nobody

– Guidewire
– Admin

– Guidewire
– Admin

gw-releasesGuidewireNobodyGuidewireGuidewire
hotfix-*

– Guidewire
– Admin

Everyone

– Guidewire
– Admin

– Guidewire
– Admin

Custom branchesEveryoneEveryoneEveryoneEveryone

For details on supported roles, see Source code in Cloud Platform documentation.

Definition

Example of a branch restriction
{
"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:

TypeDescription
NO_REWRITING_HISTORYRestrict rewriting the branch history.
NO_DELETIONRestrict deleting the branch.
NO_DIRECT_CHANGESRestrict pushing and merging directly into the branch.
NO_CHANGESRestrict 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:

TypeKeyDescription
BRANCH{branchName}Applies to the branch with the specified name.
PATTERNAccepted 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.

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 the master 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.

Example response
{
"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:

Request body
{
"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.

Example response
{
"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:

Request body
{
"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.

Example response
{
"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.

Legal and support information

Published: December 3, 2024 at 9:55 AM

© 2024 Guidewire Software, Inc.