Scale your code review with custom merge checks

Pull requests are a core feature of Bitbucket Cloud, serving as the hub where code contributions are reviewed, discussed, and approved before being merged into the codebase. Initially, developers focused on ensuring that proposed changes were bug-free, adhered to correct code styling, and included appropriate tests. Over time, the role of pull requests has expanded to act as a checkpoint, ensuring that only high-quality and compliant code reaches production.

As the responsibilities associated with pull requests grew, the need to scale and automate the review process became more pressing. Classic Merge Checks have been instrumental in this, allowing users to select from a range of predefined checks that must be satisfied before a pull request can be merged. Checks like minimum number of reviewers, successful builds, and no unresolved tasks have significantly reduced production incidents.

Recently, Bitbucket introduced custom merge checks, marking the next step in this evolution. Feedback from customers and internal Atlassian teams highlighted the demand for additional types of merge checks and greater configurability. Many use cases were highly specific – either to a certain business domain, or even a certain organisation, making it challenging to generalize solutions for the entire Bitbucket user base.

For instance, Atlassian's internal compliance requirements necessitated a merge check to ensure that each pull request was reviewed by a specific set of reviewers, based on an internal system.

Making Merge Checks pluggable

To accommodate diverse use cases, we made Merge Checks pluggable through Forge, Atlassian's Extensibility Platform. This allows anyone to quickly build and deploy extensions hosted within Atlassian's infrastructure, and then plug those extensions directly into the core Pull Request workflow, as if they were part of the native Bitbucket Cloud product. Custom Merge Checks enable customers and marketplace partners to create their own merge checks tailored to their specific needs. With just a few lines of code, you can develop a Custom Merge Check app to enforce your merging requirements.

For example, an Atlassian team created a Custom Merge Check to ensure sufficient approvals from the code owners before merging a pull request. Other use cases include checking to see if the linked Jira issue has progressed in its workflow to a ‘ready to merge’ state or calling out to the service management tool if the time is later than 5pm, to confirm that there are available support representatives before executing an after-hours deployment.

Here are links to documentation, and a step by step of how to build a sample app (one, two).

Required or recommended

Introducing new rules can often be contentious, and this is also true for rules governing when a pull request can be merged. To address this, Custom Merge Checks in Bitbucket can be configured as either “Required” or “Recommended.” Required Checks must pass for the pull request to be merged, whereas recommended checks will provide in-context advice and guidance to reviewers, without blocking the pull-request if they don't pass. This flexibility allows teams to introduce new checks and gauge their impact before making them mandatory.

For instance, you might create a Check that only allows pull requests to be merged if the code coverage remains high. Initially, this target might not be met, but it can motivate your team to improve, eventually making it an enforced standard to maintain high coding quality.

Scaling Merge Checks

Scaling the checkpoint role of code reviews goes beyond a single repository. Standardizing Checks across all repositories is crucial, particularly for larger companies. At Atlassian, we rely on custom scripts to ensure all repositories have the necessary compliance controls. Repositories without these controls are blocked from deploying.

To address use cases like this, an upcoming release of Bitbucket Custom Checks will introduce workspace- and project-level checks. This addition will enable workspace and project administrators to establish and enforce policies that apply uniformly across all repositories within their workspace.
Repository administrators will retain the flexibility to introduce additional checks specific to the unique needs of their repositories. This dual-layer approach allows for both broad standardization across the organization and granular customization at the repository level, providing the best of both worlds.

For instance, the Atlassian compliance team is working on creating a comprehensive Custom Merge Check to ensure that every pull request adheres to stringent compliance requirements. This includes verifying that each pull request undergoes a minimum number of appropriate reviews, ensuring that all reviewers have approved the latest version of the pull request, and confirming that all necessary compliance controls are enabled for the repository.

To guarantee that this Custom Merge Check is consistently applied across every Atlassian code repository, the team will leverage the new workspace-level configuration feature. This ensures that all repositories, regardless of their individual settings, adhere to the same high standards of compliance and quality.


The value of pull requests continues to grow, enhancing code quality at the repository level and serving as checkpoints for organizations to support standardization and ensure compliance across their entire codebase. Bitbucket Custom Merge Checks support this evolution by making merge checks pluggable, allowing for easy implementation of business-specific custom rulesets. Additionally, these checks can be broadly rolled out across your organisation to maintain consistent standards.

We are continually expanding the capabilities of Custom Merge Checks and are eager to hear your feedback and ideas.