As part of the graduation of custom merge checks from open-beta to general availability (GA) that is planned for late-April 2024, we're making a range of changes to several areas of the core Bitbucket Cloud workflow.
This includes changes to the core pull request review and authoring experience, as well as changes to how merge checks are configured within a repository.
Different changes will be relevant to different audiences, so feel free to use the navigation shortcuts below.
- "Classic" vs "Custom" merge checks
- Consolidating checks on pull requests
- Introduction of
on-mergechecks - Branch Configuration for Custom Merge Checks
- "Recommended" vs "Required" Custom Merge Checks
"Classic" vs "Custom" merge checks
Before discussing the changes, we need to define two terms:
- “Classic merge checks” refer to the traditional Bitbucket Cloud merge checks configured through branch restrictions in repository and project settings. They have basic UI configurability but cannot be customized.
- “Custom merge checks” refer to the new merge checks written as Forge apps by customers and third-party developers, installed, and configured to operate within specific Bitbucket Cloud workspaces.
Consolidating checks on pull requests
We’re standardizing the workflow for enforcing and addressing both custom and classic merge checks on pull requests. Previously, they appeared in separate UI cards with slightly different behaviours.
With custom merge checks’ GA release, these cards will be consolidated into one. Classic checks’ behaviour will be standardized to match the updated UX introduced during the custom merge checks beta.
Introduction of on-merge checks
We’re introducing a new concept called on-merge checks, exclusive to custom merge checks (not supported by classic checks).
Classic pre-merge checks had to pass before attempting a pull request merge. on-merge checks, however, are integrated into the merge process itself. They run immediately after the user initiates the merge workflow, verifying conditions at the exact moment of code merge. If they pass, the merge processes instantly. If they fail, the merge is blocked with real-time feedback.
For app builders, you can define your custom check as on-merge by specifying it as a trigger in the Forge app manifest.
For pull request reviewers, on-merge checks will be clearly separated from traditional pre-merge checks in the pull request sidebar and merge workflow.
“pre-merge” vs “on-merge” examples:
To better understand when to use each type:
“pre-merge” checks:
Ideal for validating the code within the pull request itself. Pull requests reference immutable, linear git commits. As long as the latest commit meets requirements, the pre-merge check can pass, regardless of when commits were pushed.
Note: Some of you may have seen the edge-case here — what happens if the logic within the custom merge check app changes between the latest commit being pushed and the merge occurring? Don't worry, the custom merge checks framework has tools built-in to detect and manage this scenario too.
“on-merge” checks:
Powerful for ensuring conditions are met at the exact merge moment. For example, blocking merges to the main branch after 5 PM Friday due to support team availability. The check runs during the merge process, validating the current state.
The key difference is that pre-merge checks validate the PR’s state at the time it was last updated, while on-merge checks validate conditions at the moment of merging.
Branch Configuration for Custom Merge Checks
Custom merge checks are configured differently from classic checks. There is a dedicated “Custom Merge Checks” tab in repository settings to manage their configuration.
The first decision is which branches the checks should run against:
“Main” Branch:
Checks configured here only run against pull requests targeting the main/development branch.
“All” Branches:
Checks configured here run against pull requests targeting all branches.
Note: You can add logic within your custom check app to make it more targeted, e.g., checking the source branch name and simply returning “success” if it doesn’t match a given pattern you determine for more refined targeting.
The flexibility is extensive, including the ability to create your own UI-based configuration screens at the workspace or repository level for custom merge check apps using Forge UI, allowing users to provide additional configuration data for the checks.
“Recommended” vs “Required” Custom Merge Checks
We’re introducing a new capability with custom merge checks that allows repository administrators to configure the level of "strictness" for each individual check.
Previously, premium workspaces could require all merge checks to pass before merging a pull request, but there was no way to make some checks "required" and others "recommended".
With custom merge checks, premium workspaces can now configure each check as either "required" or "recommended" in the repository settings.
- Required checks prevent merging if they fail, enforcing critical business rules.
- Recommended checks display as suggestions but allow merging even if they fail, enabling teams to trial new processes or receive feedback without strict enforcement.
Non-premium workspaces can still enable custom merge checks as recommendations, but they cannot prevent merging if the checks fail.
This granular configurability empowers customers to enforce essential rules while gently guiding teams toward best practices and proper workflows through recommendations.
What's next?
Custom merge checks are planned to enter GA in April. Until then, you can learn more about them and other upcoming capabilities such as dynamic pipelines on our recent update blog.
You can also get started building your own custom merge check apps today:
- We have comprehensive guides available on creating your own Forge apps in Bitbucket Cloud.
- Full example project repositories for custom merge checks.
- And pre-recorded live-code webinars to help you get started.
We will also be running a second live-code webinar focused on more advanced Custom Merge Check use-cases in early April, so come along and see how easy it is to get started.
