Bitbucket modules
Common modules
Compass modules
Confluence modules
Jira modules
Jira Service Management modules

We are releasing a limited set of Bitbucket modules, events, and APIs under Forge's Early Access Program (EAP). This will allow you to start building Bitbucket apps through the Forge platform.

For more information about this EAP, see the related changelog entry here.

Forge’s EAP offers experimental features to selected users for testing and feedback purposes. These features are not supported or recommended for use in production environments. They are also subject to change without notice.

For more information, see Forge EAP, Preview, and GA.

Custom Merge Check (EAP)

The bitbucket:mergeCheck module defines a custom merge check that runs in the context of a pull request. The module allows a Forge app to define checks that prevent pull requests from merging in Bitbucket until the specified conditions have been met.

The bitbucket:mergeCheck module is conceptually similar to the Forge trigger module in that the Forge infrastructure will invoke the module only when the subscribed event occurs. A key difference is that bitbucket:mergeCheck is triggered by granular, merge check specific, pull request focused events, as opposed to more general Product events.

Another key difference is that the bitbucket:mergeCheck module must return a response payload that indicates whether the check has passed or failed.

Example of a bitbucket:mergeCheck in a pull request

Each module will be treated as its own check and have independent results, all of which must be passed for a pull request to be merged. The check results are rendered on the pull request page, which will help to guide the user towards the changes needed for the check to pass.

Once a Forge app with a bitbucket:mergeCheck module has been installed into a Bitbucket workspace, the workspace admin must enable the Custom merge checks feature in the workspace settings before they can be used.

After this a repository admin must configure whether or not each bitbucket:mergeCheck should be run in the repository settings for each repository they wish to utilize the check.



A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$


A reference to the key of the function that defines the check behavior.

This function must return a check result.


The name of the check which is displayed throughout the UI.


The list of triggers is subscribed to / will be triggered by.

Requires at least 1 element.


The snippet below defines a merge check that will be triggered when any commits have been pushed to the source branch of the pull request.

    - key: my-bitbucket-custom-merge-check
      function: check-function-impl
      name: My first custom merge check
      description: This is my first check
        - on-code-pushed
    - key: check-function-impl
      handler: index.myCheckFunction


The triggers provide a mechanism for the bitbucket:mergeCheck module to control when the check should be invoked for a given pull request. These can be seen as business events within the lifecycle of a pull request.

A bitbucket:mergeCheck module can subscribe to one or more existing triggers. This decision should be based on what the check is checking. For instance, a check trying to enforce a code quality standard may only require the on-code-pushed trigger, while a check preventing pull requests from being merged during a weekend may only require the on-merge trigger.

It's important to remember that, unlike traditional Forge Functions, bitbucket:mergeCheck triggers will only invoke the subscribed merge check functions if the repository that the event occurs within has the respective check enabled for that repository. This prevents unnecessary invocations of the Forge functions containing the custom merge check logic.

on-code-pushed pre-merge

Will invoke the check every time new or updated commits are pushed to the source branch of the pull request.

on-merge on-merge

Will invoke the check as part of the process of merging the pull request. When the user attempts to merge the pull request, all on-merge custom merge checks will immediately be run, prior to the merge completing.

If this type of check fails, the merge will be aborted. To retry the failed on-merge checks, another attempt merge can be attempted by the user.

Invocation payload

Whenever a bitbucket:mergeCheck module is invoked, an event payload will be provided as an argument to the Forge function. This payload provides the identifiers of the pull request that the check is being invoked against.




The workspace containing the pull request the check is running against.



The repository containing the pull request the check is running against.



The pull request the check is running against.



The trigger that caused the invocation of the check.

Type reference

interface Workspace {
  uuid: string;

interface Repository {
  uuid: string;

interface PullRequest {
  id: number;

interface Trigger {
  type: string;

interface PRCheckEvent {
  workspace: Workspace;
  repository: Repository;
  pullrequest: PullRequest;
  trigger: Trigger;


  "workspace": {
    "uuid": "{cc8e193d-7603-4dfd-8771-fcc8960aa0fb}"
  "repository": {
    "uuid": "{15a31549-1cff-45dc-9d0d-310114c5038b}"
  "pullrequest": {
    "id": 123
  "trigger": {
    "type": "on-code-pushed"

Response payload

The only responsibility of the function registered against the bitbucket:mergeCheck module is that it returns a well-defined response payload every time the Bitbucket Forge infrastructure invokes it.

This result produced by each invocation of the bitbucket:mergeCheck module is handled and stored by the Bitbucket Forge infrastructure, there is no requirement for the Forge app to store it, or send the response back to a specific Bitbucket API. The merge check is only expected to calculate and return result in the correct response format.

If any exceptions are thrown when executing the check logic, the check result will be treated as a failure. Note that the user can individually rerun failed checks.

Example of a bitbucket:mergeCheck in a pull request, annotated with identifiers

  1. Merge check result: derived from response payload success field.
  2. Merge check name: derived from the module name field.
  3. Merge check message: derived from the response payload message field.


success boolean Yes

Whether or not the check has passed.

If false Bitbucket will prevent the pull request from being merged.

message string No

A message related to the result of the check.

Useful for providing detail to the users about why the check failed, giving hints to what needs to be fixed in the pull request.

Type reference

interface MergeCheckResponse{
  success: boolean;
  message?: string;


  "success": false,
  "message": "No merges after 5pm"

Rate this page: