Configure merge checks
Learn how to use the Repository Settings API to configure merge checks.
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 modify the merge check configuration. |
repositoryName | Name of a repository. See supported repositories. |
About merge checks
By configuring merge checks, you make sure that only the pull requests that meet the specified conditions can be merged into the target branch.
Default configuration
Merge check configuration is defined on the project level and, by default, inherited by each repository. You can customize this configuration separately for each repository in your star system.
Note that the merge check configuration applies to all branches within a repository.
You can configure the following merge checks:
Key | Description | Default configuration |
---|---|---|
ALL_REVIEWERS_APPROVE | Blocks the merge until all the reviewers approve the pull request. | Disabled |
MINIMUM_APPROVALS | Blocks the merge until the pull request receives at least the specified number of approvals. | Disabled |
MINIMUM_SUCCESSFUL_BUILDS | Blocks the merge until there is at least the specified number of successful builds. | Disabled |
NO_NEEDS_WORK_STATUS | Blocks the merge if any reviewer marked the pull request as needs work . | Disabled |
NO_INCOMPLETE_TASKS | Blocks the merge if there are any incomplete tasks. | Disabled |
You can't modify a project (star system) level configuration with the Repository Settings API.
Get configuration
To retrieve a list of merge checks configured for your repository, send the following GET
request:
curl -X 'GET' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/merge-checks' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access_token}'
Response contains a JSON object with the merge check configuration, for example:
[
{
"key": "ALL_REVIEWERS_APPROVE",
"name": "All reviewers approve",
"description": "Require all reviewers to approve the pull request.",
"enabled": true,
"scope": {
"type": "REPOSITORY"
},
"settings": null
},
{
"key": "MINIMUM_APPROVALS",
"name": "Minimum approvals",
"description": "Require at least the specified number of approvals.",
"enabled": true,
"scope": {
"type": "REPOSITORY"
},
"settings": {
"requiredCount": 1
}
},
{
"key": "MINIMUM_SUCCESSFUL_BUILDS",
"name": "Minimum successful builds",
"description": "Require at least the specified number of successful builds.",
"enabled": true,
"scope": {
"type": "REPOSITORY"
},
"settings": {
"requiredCount": 12
}
},
{
"key": "NO_NEEDS_WORK_STATUS",
"name": "No 'needs work' status",
"description": "Block the merge if any reviewers have marked the pull request as 'needs work'.",
"enabled": false,
"scope": {
"type": "PROJECT"
},
"settings": null
},
{
"key": "NO_INCOMPLETE_TASKS",
"name": "No incomplete tasks",
"description": "Require all tasks to be complete.",
"enabled": false,
"scope": {
"type": "PROJECT"
},
"settings": null
}
]
Modify a merge check
To modify a merge check configuration for a repository, send the following PUT
request:
curl -X 'PUT' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/merge-checks/{mergeCheckKey}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{body}'
Where:
{mergeCheckKey}
specifies the merge check to update.{body}
contains the updated configuration.
For example, to require at least two approvals to merge a pull request, use the following:
{
"enabled": true,
"settings": {
"requiredCount": 2
}
}
For a successful request, you will receive the 200
status code and the currently defined merge check configuration.
{
"key": "MINIMUM_APPROVALS",
"name": "Minimum approvals",
"description": "Require at least the specified number of approvals.",
"enabled": true,
"scope": {
"type": "REPOSITORY"
},
"settings": {
"requiredCount": 2
}
}
Restore default configuration
By deleting a merge check, you restore the default configuration. To delete a merge check, send the following DELETE
request:
curl -X 'DELETE' \
'{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/merge-checks/{mergeCheckKey}' \
-H 'Accept: */*' \
-H 'Authorization: Bearer {access_token}'
For a successful request, you will receive the 204
status code.
Was this page helpful?