Custom Merge Check

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 can 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.

Each module will be treated as its own check and have independent results. A check must pass for a pull request to be merged if it is configured to be Required in Repository Settings. If the check is configured to be Recommended, then it is informational only and will not block pull request merge. 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.

Properties

Example

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.

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

Scope

In order to subscribe to bitbucket:mergeCheck triggers, you need to add read:pullrequest:bitbucket scope to your app manifest.

Triggers

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 validating. 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.

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, and additional properties where applicable.

Type reference

1
2
interface Workspace {
  uuid: string;
}

interface Repository {
  uuid: string;
}

interface PullRequest {
  id: number;
}

interface Trigger {
  type: string;
}

interface MergeProperties {
  commitMessage: string;
  commitMessageTruncated: boolean;
  mergeStrategy: string;
  closeSourceBranch: boolean;
}

interface PRCheckEvent {
  workspace: Workspace;
  repository: Repository;
  pullrequest: PullRequest;
  trigger: Trigger;
  mergeProperties?: MergeProperties;
}

Example

This is an example payload of an on-code-pushed trigger.

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

Example

This is an example payload of an on-merge trigger.

1
2
{
  "workspace": {
    "uuid": "{cc8e193d-7603-4dfd-8771-fcc8960aa0fb}"
  },
  "repository": {
    "uuid": "{15a31549-1cff-45dc-9d0d-310114c5038b}"
  },
  "pullrequest": {
    "id": 123
  },
  "trigger": {
    "type": "on-code-pushed"
  },
  "mergeProperties": {
    "commitMessage": "Merged in testbranch (pull request #5)\n\ntesting PR\n\n",
    "commitMessageTruncated": false,
    "mergeStrategy": "merge_commit",
    "closeSourceBranch": true
  }
}

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.

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.

Properties

Type reference

1
2
interface MergeCheckResponse{
  success: boolean;
  message?: string;
}

Example

1
2
{
  "success": false,
  "message": "No merges after 5pm"
}