Skip to main content

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 nameDescription
tenantIdYour tenant ID.
starSystemIdID of a star system that includes the repository for which you modify the merge check configuration.
repositoryNameName 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:

KeyDescriptionDefault configuration
ALL_REVIEWERS_APPROVEBlocks the merge until all the reviewers approve the pull request.Disabled
MINIMUM_APPROVALSBlocks the merge until the pull request receives at least the specified number of approvals.Disabled
MINIMUM_SUCCESSFUL_BUILDSBlocks the merge until there is at least the specified number of successful builds.Disabled
NO_NEEDS_WORK_STATUSBlocks the merge if any reviewer marked the pull request as needs work.Disabled
NO_INCOMPLETE_TASKSBlocks the merge if there are any incomplete tasks.Disabled
note

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:

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

Request body
{
"enabled": true,
"settings": {
"requiredCount": 2
}
}

For a successful request, you will receive the 200 status code and the currently defined merge check configuration.

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

Legal and support information

Published: December 3, 2024 at 9:55 AM

© 2024 Guidewire Software, Inc.