Configure automatic merging for pull requests

Learn how to use the Repository Settings API to configure whether pull requests are automatically merged after they complete all 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 that you want to configure.
repositoryName	Name of a repository. For details, see Supported repositories.

About automatic merging

When you enable automatic merging for a repository, the standard merge option changes to a Merge when ready button. When you select this merge option, Bitbucket merges that specific pull request automatically as soon as it completes every required merge check, such as minimum approvals or successful builds.

Default automatic merge configuration

By default, automatic merging is disabled based on your Dev star system settings. You can configure automatic merging separately for each repository in your Dev star system.

Note:

With the Repository Settings API, you can't modify the configuration at the Bitbucket project level.

Get automatic merge configuration

To retrieve the current automatic merge configuration for a repository, send the following GET request:

curl -X 'GET' \
  '{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/branches/automerge' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

The response contains a JSON object with the current configuration, for example:

Example response

{
  "enabled": false
}

Update automatic merge configuration

To update the automatic merge configuration for a repository, send the following PUT request:

curl -X 'PUT' \
  '{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/branches/automerge' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{body}'

Where {body} contains the updated configuration. For example, to enable automatic merging, send the request with the following {body}:

Request body

{
  "enabled": true
}

For a successful request, you will receive the 200 status code and the updated configuration:

Example response

{
  "enabled": true
}