Repository Merge Check Plugin Module

Introduction

A repository merge check module defines a Java component that can veto a request by a user to merge a pull request. A vetoed pull request will be prevented from merging and feedback is given to the user explaining why the merge can't proceed.

Example merge checks might include:

  • A check that requires at least two reviewers on a pull request (to ensure adequate review coverage)
  • A check that requires all reviewers must first approve a pull request prior to it being merged (to achieve consensus)
  • A check that requires the latest Bamboo build related to a pull request's source branch should be green (to help preserve CI success in the target branch)

Note: although merge checks restrict the merge operation within Bitbucket Server, they do not prevent users from merging branches in their local clones and pushing this change. Please look at branch permissions for this functionality.

Please see the how-to guide for more information on creating a repository merge check.

Configuration

The root element for the Repository Merge Check plugin module is <repository-merge-check/>. It allows the following attributes for configuration:

Attributes

NameRequiredDescriptionDefault
keyYesThe identifier of the plugin module. This key must be unique within the plugin where it is defined.N/A
classYesThe fully qualified Java class name of the merge check. This class must implement RepositoryMergeCheck. N/A
nameYesThe human-readable name of the plugin module.N/A
i18n-name-key The i18n key of the human-readable name of the plugin module. If defined, this name will be displayed in the Repository Settings > Hooks section instead of the value provided in the 'name' attributeN/A
configurable Whether the merge check can be enabled or disabled at the repository level. If set to false, the merge check will enabled for all repositories and will not be displayed in the Repository Settings > Hooks section. true

Elements

NameRequiredDescriptionDefault
description The description of the plugin module. The 'key' attribute can be specified to declare a localisation key for the value instead of text in the element body. N/A
icon Repository merge checks are able to display a customised icon on the administration screen. Regardless of the original size, this icon will be scaled to 48x48 px. N/A
config-form Repository merge checks are able to have additional per-repository settings that are automatically passed to your merge check. Configuration form modules are used to describe a simple configuration form that will be automatically saved, loaded and validated. See below for more details. N/A
validator The class of the validation component that will perform setting validation before save. This class must implement com.atlassian.bitbucket.setting.RepositorySettingsValidator. Alternatively this interface can be applied on the merge check instead, and this element can be ignored. N/A

Config-Form Elements

These are the elements required for the config-form element.

NameRequiredDescriptionDefault
directoryYes A directory that contains any custom Soy, JavaScript and CSS files required to implement the view. N/A
viewYes A JavaScript function that will be invoked to display the form. This function will be expected to return HTML which may be generated via Soy or some other mechanism, ideally using AUI for consistency.

For more information about AUI please visit the sandbox. For an a list of available Soy templates that you can use in your own configuration form, consult the source.

N/A

Simple Example

Here is an example atlassian-plugin.xml file containing just a repository merge check. The merge check in this example is enabled for all repositories (because of configurable="false").

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}" plugins-version="2">
    <plugin-info>
        <description>${project.description}</description>
        <version>${project.version}</version>
        <vendor name="${project.organization.name}" url="${project.organization.url}" />
        <param name="plugin-icon">images/pluginIcon.png</param>
        <param name="plugin-logo">images/pluginLogo.png</param>
    </plugin-info>

    <!-- add our i18n resource -->
    <resource type="i18n" name="i18n" location="is-admin-merge-check"/>

    <repository-merge-check key="isAdmin" class="bean:isAdminMergeCheck" configurable="false"/>
</atlassian-plugin>

Full Example

Here is an example atlassian-plugin.xml file containing a repository merge check and an configuration form that is validated.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<atlassian-plugin name="My Repository Merge Check Example" key="example.plugin.mymergecheck" plugins-version="2">
    <plugin-info>
        <description>A basic merge check plugin</description>
        <vendor name="My Company" url="http://www.mycompany.com"/>
        <version>1.0</version>
    </plugin-info>

    <repository-merge-check key="exampleMergeCheck" name="Requires Green Build" 
                     class="com.mycompany.example.plugin.mymergecheck.MyRepositoryMergeCheck">
        <!-- Optional -->
        <icon>icons/greenbuild.png</icon>
        <!-- Optional -->
        <config-form name="Simple Config" key="simpleMergeCheck-config">
            <view>bitbucket.config.example.mergecheck.simple</view>
            <directory location="/static/"/>
        </config-form>
        <!-- Optional -->
        <validator>com.mycompany.example.plugin.mymergecheck.MyValidator</validator>
    </repository-merge-check>

</atlassian-plugin>

More Examples

You can find some concrete examples on the how-to guide and the 'Controlling when pull requests can be merged' tutorial.