Support for Server products ended Feb. 15, 2024. Learn what this means for you.

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 Data Center. 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

Name	Required	Description	Default
key	Yes	The identifier of the plugin module. This key must be unique within the plugin where it is defined.	N/A
class	Yes	The fully qualified Java class name of the hook. This class must implement PreRepositoryHook or PostRepositoryHook	N/A
name	Yes	The 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' attribute	N/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

Name	Description	Default
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.

Name	Required	Description	Default
directory	Yes	A directory that contains any custom Soy, JavaScript and CSS files required to implement the view.	N/A
view	Yes	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
<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
<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.