Repository Hook Plugin Module

Introduction

Repository Hook modules are used to plug in to the different ways in which branches and tags are updated in Bitbucket Server. This can be useful for blocking some pushes, merges or updating an external entity based on the new repository state.

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

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 hook. This class must implement PreRepositoryHook or PostRepositoryHook 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 hook can be enabled or disabled at the repository level. If set to false, the hook will enabled for all repositories and will not be displayed in the Repository Settings > Hooks section. N/A

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 hooks 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 hooks are able to have additional per-repository settings that are automatically passed to your hook. 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 hook 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 hook.

1
2
3
4
5
6
7
8
9
10
11
<atlassian-plugin name="My Repository Hook Example" key="example.plugin.myhook" plugins-version="2">
    <plugin-info>
        <description>A basic hook plugin</description>
        <vendor name="My Company" url="http://www.mycompany.com"/>
        <version>1.0</version>
    </plugin-info>

    <repository-hook key="examplePreReceiveHook" name="Stop force pushes" 
                     class="com.mycompany.example.plugin.myhook.MyRepositoryHook" />

</atlassian-plugin>

Full Example

Here is an example atlassian-plugin.xml file containing a repository hook 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 Hook Example" key="example.plugin.myhook" plugins-version="2">
    <plugin-info>
        <description>A basic hook plugin</description>
        <vendor name="My Company" url="http://www.mycompany.com"/>
        <version>1.0</version>
    </plugin-info>

    <repository-hook key="examplePreReceiveHook" name="Stop force pushes" 
                     class="com.mycompany.example.plugin.myhook.MyRepositoryHook">
        <!-- Optional -->
        <icon>icons/hook.png</icon>
        <!-- Optional -->
        <config-form name="Simple Hook Config" key="simpleHook-config">
            <view>bitbucket.config.example.hook.simple</view>
            <directory location="/static/"/>
        </config-form>
        <!-- Optional -->
        <validator>com.mycompany.example.plugin.myhook.MyValidator</validator>
    </repository-hook>

</atlassian-plugin>

More Examples

You can find some concrete examples on the how-to guide.