Skip to main content

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 nameDescription
tenantIdYour tenant ID.
starSystemIdID of a star system that includes the repository for which you configure the default reviewers.
repositoryNameName 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.

note

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.

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

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

TypeKeyDescription
ANY_REFnullApplies to all branches.
BRANCH{branchName}Applies to the branch with the specified name. The refs/heads/ prefix is added automatically if missing.
PATTERNAccepted wild cards: ?, *, **Applies to every branch whose name matches the pattern. For details, see Branch patterns.
MODEL_BRANCHproduction or developmentApplies to all branches of the specified model.
MODEL_CATEGORYBUGFIX, FEATURE, HOTFIX, or RELEASEApplies to all branches of the specified category.
Use uppercase letters.
note

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.

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

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

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

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

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

Legal and support information

Published: December 3, 2024 at 9:55 AM

© 2024 Guidewire Software, Inc.