Configure default reviewers
Learn how to use the Repository Settings API to configure default reviewers.
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 default reviewers. |
repositoryName | Name of a repository. See supported repositories. |
About default reviewers
By configuring default reviewers, you ensure that the specified people are automatically added as reviewers to all the new pull requests that match the defined source and target branches. You can also define how many of the default reviewers must approve a pull request before it can be merged into the target branch.
Default configuration
By default, there are no reviewers or required approvals configured for your repositories. This configuration is defined on the star system level and, by default, inherited by each repository. You can create a different custom configuration for each repository in your star system.
You can't modify a project (star system) level configuration with the Repository Settings API.
Conditions
A condition represents a part of the custom configuration for a repository. By creating a condition, you specify the following:
- Source and target branch
- Reviewers
- Number of required approvals
To better reflect your development practices, you can create multiple conditions for a repository.
Example
If you require a tech lead to control all changes merged into the master branch but also want to keep a number of stakeholders informed about these changes, create two different conditions:
- With the first condition, define the tech lead as a default reviewer and set the number of required approvals to one.
- With the second condition, define the stakeholders as default reviewers and set the number of required approvals to zero.
For both conditions, specify master
as a target branch and ANY_REF
as a source branch.
Definition
{
"id": "1",
"scope": {
"type": "REPOSITORY"
},
"sourceBranch": {
"key": null,
"type": "ANY_REF",
"active": true
},
"targetBranch": {
"key": "master",
"type": "BRANCH",
"active": true
},
"reviewers": [
{
"name": "user@example.com",
"displayName": "Reviewer 1"
}
],
"requiredApprovals": 1
}
ID and scope
Condition ID is generated automatically and is unique at a tenant level.
Each condition has also a specific scope. The scope
parameter has one of the following values:
PROJECT
indicates that a condition is inherited and defined at the star system level.REPOSITORY
indicates a custom condition. Every condition that you create using the Repository Settings API has this scope.
Branches
A condition applies to all the pull requests from the specified source branch to the specified target branch.
To define a branch, use the type
and key
parameters:
Type | Key | Description |
---|---|---|
ANY_REF | null | Applies to all branches. |
BRANCH | {branchName} | Applies to the branch with the specified name. The refs/heads/ prefix is added automatically if missing. |
PATTERN | Accepted wild cards: ? , * , ** | Applies to every branch whose name matches the pattern. For details, see Branch patterns. |
MODEL_BRANCH | production or development | Applies to all branches of the specified model. |
MODEL_CATEGORY | BUGFIX , FEATURE , HOTFIX , or RELEASE | Applies to all branches of the specified category. Use uppercase letters. |
The values available for MODEL_BRANCH
and MODEL_CATEGORY
depend on your branch configuration.
Reviewers
To define a default reviewer, 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.
Required approvals
The number of required approvals specifies how many of the default reviewers must approve the pull request before it can be merged into the target branch.
If you want to require an approval from a specific user, create a separate condition with that user as the only default reviewer and set a number of required approvals to one.
Configure default reviewers
You configure default reviewers for a repository by creating, modifying, and deleting conditions.
Get configuration
To retrieve the configuration of a repository, send the following GET
request:
curl -X 'GET' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/default-reviewers' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access_token}'
Response contains a JSON object with all the conditions that are currently configured for this repository.
[
{
"id": "1",
"scope": {
"type": "REPOSITORY"
},
"sourceBranch": {
"key": null,
"type": "ANY_REF",
"active": true
},
"targetBranch": {
"key": "master",
"type": "BRANCH",
"active": true
},
"reviewers": [
{
"name": "user@example.com",
"displayName": "Reviewer 1"
}
],
"requiredApprovals": 1
},
{
"id": "2",
"scope": {
"type": "REPOSITORY"
},
"sourceBranch": {
"type": "MODEL_BRANCH",
"active": true,
"key": "development"
},
"targetBranch": {
"type": "MODEL_CATEGORY",
"active": true,
"key": "BUGFIX"
},
"reviewers": [
{
"name": "user2@example.com",
"displayName": "Reviewer 2"
},
{
"name": "user3@example.com",
"displayName": "Reviewer 3"
}
],
"requiredApprovals": 0
}
]
If there aren't any conditions configured for a respository, the response will be empty.
Create a condition
To create a condition, send the following POST
request:
curl -X 'POST' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/default-reviewers' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{body}'
Where {body}
defines the condition.
For example, to add user@example.com
as a default reviewer to pull requests from all development
branches to master
, and require that user's approval, use the following:
{
"sourceBranch": {
"key": "development",
"type": "MODEL_BRANCH"
},
"targetBranch": {
"key": "master",
"type": "BRANCH"
},
"reviewers": ["user@example.com"],
"requiredApprovals": 1
}
For a successful request, you will receive the 200
status code and the created condition with an ID and scope.
{
"id": "1",
"scope": {
"type": "REPOSITORY"
},
"sourceBranch": {
"key": "development",
"type": "MODEL_BRANCH",
"active": true
},
"targetBranch": {
"key": "master",
"type": "BRANCH",
"active": true
},
"reviewers": [
{
"name": "user@example.com",
"displayName": "Reviewer 1"
}
],
"requiredApprovals": 1
}
Modify a condition
To modify an existing condition, send the following PUT
request:
curl -X 'PUT' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/default-reviewers/{defaultReviewerConditionId}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{body}'
Where:
{defaultReviewerConditionId}
is an ID of the condition that you want to modify.{body}
contains the modified condition.
For example, to modify the condition created in the previous step by adding one more reviewer, use the following:
{
"sourceBranch": {
"key": "development",
"type": "MODEL_BRANCH"
},
"targetBranch": {
"key": "master",
"type": "BRANCH"
},
"reviewers": ["user@example.com", "user@guidewire.com"],
"requiredApprovals": 1
}
For a successful request, you will receive the 200
status code and the updated condition.
{
"id": "1",
"scope": {
"type": "REPOSITORY"
},
"sourceBranch": {
"key": "development",
"type": "MODEL_BRANCH"
"active": true
},
"targetBranch": {
"key": "master",
"type": "BRANCH"
"active": true
},
"reviewers": [
{
"name": "user@example.com",
"displayName": "Reviewer 1"
},
{
"name": "user@guidewire.com",
"displayName": "Reviewer 2"
}
],
"requiredApprovals": 1
}
Delete a condition
To delete a condition, send the following DELETE
request:
curl -X 'DELETE' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/default-reviewers/{defaultReviewerConditionId}' \
-H 'Accept: */*' \
-H 'Authorization: Bearer {access_token}'
Where {defaultReviewerConditionId}
is an ID of the condition that you want to delete.
For a successful request, you will receive the 204
status code.
Was this page helpful?