Note:
This feature is currently in open beta in order to gather feedback, and accelerate our path to maximum value for our customers.
Sign up for a webinar on April 9th, 2024, to learn more about how to set up a custom check.
Bitbucket Cloud is on a mission to become the most extensible cloud SCM and CI/CD product in the market. We believe that extensibility is a key enabler for large, complex organisations to operate effectively in the cloud, and we are excited to be leveraging Atlassian’s industry-leading extensibility platform, Forge, to bring this mission to life.
When we announced Forge for Bitbucket Cloud, it was the first step on our journey towards turning Bitbucket Cloud into not just a product, but a true DevOps Automation Platform.
Today, we’re excited to announce the next stage of that journey, Custom Merge Checks.
What are merge checks?
Those of us who use Bitbucket Cloud as part of their day to day development would likely be familiar with the existing merge checks that must pass before a Pull Request can be merged.
In basic terms, merge checks can be thought of as test cases for your PR; they're testing that the PR has met a set of requirements configured for your repository. These merge checks are configured at the repository level, or the project level by an admin.
At Atlassian, we have many compliance requirements for our codebases / services. We rely on merge checks as a mechanism to enforce some of these requirements. We also have teams that have their own specific rules and processes they'd like to be able to enforce. This makes building a one size fits all solution very hard.
Bitbucket's current Merge Check implementation is limited. You can't extend the list of predefined checks that Bitbucket Cloud offers, and you're only able to change basic configuration which predicates what each merge check tests against such as The number of required builds or The number of required approvals.
Introducing Custom Merge Checks, powered by Forge
The Bitbucket Cloud team has been working on a new feature that will enable our customers to create custom merge checks targeting their unique use-cases. These checks will be triggered throughout stages in the Pull Request lifecycle, and will be required to have run and passed prior to a PR being merged.
We leveraged Forge to serve as the foundation for this new capability. Forge provides a myriad of useful features out of the box which Custom Merge Checks can be built from; UI components, forge storage and simple, but secure authentication for Bitbucket's API.
Another benefit of Forge is the developer experience that comes along with it. Forge empowers developers to quickly iterate and integrate with Bitbucket Cloud’s APIs to power their merge checks. Also, because Forge is a "Function-as-a-Service" platform, it means app developers do not need to deploy and maintain infrastructure to produce functionality like Custom Merge Checks.
In Bitbucket Cloud, Forge apps are installed into workspaces. All repositories contained in the workspace have access to the Custom Merge Checks provided by the app, but their enforcement is managed at a per-repo level in the repository settings.
Important Note
In the future, we plan to implement this hierarchically, meaning Workspace Admins or Project Admins can enforce which merge checks should be enabled on all repositories under their scope.
Why are we building Custom Merge Checks?
There is a fundamental issue that occurs when software tools grow to support larger and more complex customers and users. As the companies using a product get more complicated and unique, it becomes increasingly difficult to meet those unique and vastly different requirements with standard off-the-shelf features.
This leads to something we're all familiar with, a terrifyingly complex enterprise software tool that has a 1000 different features, 990 of which only a small handful of customers ever use. This becomes impossible to maintain, hard to learn, and stifles innovation and improvements due to the complexity these new features can add to a codebase.
To avoid this, Bitbucket Cloud is aiming to provide customers with a suite of powerful, yet easy to use tools to add their own custom logic directly into the core workflows of the product. This will allow customers who have complex or niche requirements to implement process and policy controls inside Bitbucket Cloud that can meet 100% of their use-cases, no matter how bespoke or specific they might be. At the same time, it avoids the risk of "complexity bloat" mentioned previously, by allowing the Bitbucket Cloud product to focus on the core SCM and CI/CD capabilities and workflows.
It also provides a powerful framework to support App Partners to develop Apps that solve common sets of problems experienced by customers in ways that are different to those provided natively in the core product.
What can we do with Custom Merge Checks?
Custom merge checks provide a scaffold that enables individual teams / organisations to build solutions to their unique problems, directly on top of Bitbucket Cloud.
There is an endless list of potential Custom Merge Checks use-cases, but some examples from internal testing include:
- All commits / PR title contains a Jira issue
- Prevent a PR from being merged outside of business hours
- Prevent a PR from being merged whilst there is a release blocker / ongoing incident
- Code owners (Require particular default reviewers approvals based on the files changed in the PR)
- Security scanning has to be run
- A PR isn't too big / complex
- A PR cannot be merged if it's reliant on other Pull Requests
- A PR cannot be merged if it's too stale (How long it has been since it was last updated)
- PR Description standards check
- Linked feature flag check
- Required minimum level unit test coverage
Checks are run against a PR in response to "Triggers" that the Check app is subscribed to. So far we have implemented two triggers, with more planned as part of the Open Beta.
They are:
on-code-pushed– This is triggered whenever the source branch of a PR is updated. This is an asynchronous merge check. The PR cannot be merged unless allon-code-pushedtriggered checks have already passed.on-merge– This is triggered during the merge process. These triggered checks will be synchronously invoked just prior to the actual git merge. If these checks fail, the merge is aborted.
What does the PR flow look like with Custom Merge Checks?
In the demo above, the repository has two Custom Merge Checks enabled. The first ensures that all commit messages in the PR have a Jira issue in the commit message. This runs when the PR is first created, it would also be invoked whenever any new commits are pushed to the source branch.
Once that check has passed, the pull request can be merged. The merge dialog then displays the on-merge checks that will run as part of the merge process. This ensures that the title of the PR contains a Jira issue.
Pressing the merge button triggers the invocation of this second check, and once passed, the git merge process begins, and the PR is closed.
For more details on all the supported workflows, take a look at the custom merge checks documentation https://developer.atlassian.com/platform/forge/manifest-reference/modules/bitbucket-merge-check/
Important notE:
Note that these custom checks are rendered alongside the original merge checks. With the new functionality enabled, we require both the original merge checks and the Custom Merge Checks to pass prior to merging.
Great, how do I get started?
Step 1. Understand how to build a Forge app in Bitbucket Cloud
As Custom Merge Checks are implemented using Forge, you'll need to familiarise yourself with building Forge apps in Bitbucket Cloud. Forge Apps are extremely simple to build – most teams are able to have something up and running in less than 30 minutes.
There is documentation on developer.atlassian.com which will help get you up to speed:
Step 2. Extend your Forge App with the Custom Merge Checks functionality
Once you've got your base Forge app setup, it's time to extend it with a new bitbucket:mergeCheck module.
Documentation on how to do this can be found here:
Step 3. Install and test your Custom Merge Check App
Install your Forge App that implements a Custom Merge Check into your Bitbucket Cloud Workspace. Once done, you will need to enable the Workspace level "Custom Merge Checks" feature toggle under the new "Custom Merge Checks" section in your Workspace settings.
Note: Forge is not supported on Personal Workspaces. In order to use any Forge based functionality, you must be operating within a Shared Workspace. For more information, see: Difference between shared and personal workspaces.
Once the feature is enabled, any Forge Apps installed into your Workspace that implement a Custom Merge Check will appear in the "Custom Merge Checks" page under the Repository Settings for all repositories in that Workspace. Repository admins can activate the Custom Merge Checks they want to have run against Pull Requests for that repository from the repository settings.
Getting help, providing feedback, sharing ideas?
The community space will be the primary place for collaboration and communication during the open beta. We will share important updates there like new capability releases, roadmap updates, and any breaking changes.
This will also be where we will provide support to people participating in the open beta. If you have questions or need support, please create a post in that space so that we can help you get going. If you see someone else asking for help and you have an answer, please get involved so we can build this community up and make it valuable for everyone.
Please also use this space to provide feedback, request features, and let us know about any bugs or rough edges you find. We're committed to making the custom merge checks experience in Bitbucket Cloud the best we can, but we'll need your input to make that happen. Also note that it's just as important for us to get feedback on our documentation, tutorials, and guides – so if you find something that doesn't make sense, please let us know so we can make it right.
And finally, when you build a custom merge check for your team that solves something painful, please share it with our community so that others can learn from your success. We're excited to see what people build, and the more ideas we see people implementing, the more ideas we can come up with to unlock even more potential.