# Repository Hook Plugin Module

## Introduction

Repository Hook modules are used to plug in to the pushing and merging lifecycle of Bitbucket Server.
This can be useful for blocking some pushes (pre-receive), merges (merge-check) or updating an external entity based
on the new repository state (post-receive).

Please see the [how-to guide](../../how-tos/repository-hooks.html) for more information on creating a repository hook.

## Configuration

### Attributes

<table>
    <tr>
        <th>Name</th>
        <th>Required</th>
        <th>Description</th>
        <th>Default</th>
    </tr>
    <tr>
        <td>key</td>
        <td><span class="tick" /></td>
        <td>The identifier of the plugin module. This key must be unique within the plugin where it is defined.</td>
        <td>N/A</td>
    </tr>
    <tr>
        <td>class</td>
        <td><span class="tick" /></td>
        <td>The fully qualified Java class name of the hook. This class must implement
            <a href="https://developer.atlassian.com/static/javadoc/bitbucket-server/${project.version}/spi/reference/com/atlassian/bitbucket/hook/repository/PreReceiveRepositoryHook.html">PreReceiveRepositoryHook</a>,
            <a href="https://developer.atlassian.com/static/javadoc/bitbucket-server/${project.version}/spi/reference/com/atlassian/bitbucket/hook/repository/AsyncPostReceiveRepositoryHook.html">AsyncPostReceiveRepositoryHook</a> or
            <a href="https://developer.atlassian.com/static/javadoc/bitbucket-server/${project.version}/spi/reference/com/atlassian/bitbucket/hook/repository/RepositoryMergeRequestCheck.html">RepositoryMergeRequestCheck</a>
         </td>
        <td>N/A</td>
    </tr>
    <tr>
        <td>name</td>
        <td></td>
        <td>The human-readable name of the plugin module.</td>
        <td>N/A</td>
    </tr>
</table>

### Elements

<table>
    <tr>
        <th>Name</th>
        <th>Required</th>
        <th>Description</th>
        <th>Default</th>
    </tr>
    <tr>
        <td>description</td>
        <td></td>
        <td>
            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.
        </td>
        <td>N/A</td>
    </tr>
    <tr>
        <td>icon</td>
        <td></td>
        <td>
            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.
        </td>
        <td>N/A</td>
    </tr>
    <tr>
        <td>config-form</td>
        <td></td>
        <td>
            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 <a href="#Config-Form_Elements">below</a> for more details.
        </td>
        <td>N/A</td>
    </tr>
    <tr>
        <td>validator</td>
        <td></td>
        <td>
            The class of the validation component that will perform setting validation before save.
            This class must implement <code>com.atlassian.bitbucket.setting.RepositorySettingsValidator</code>.
            Alternatively this interface can be applied on the hook instead, and this element can be ignored.
        </td>
        <td>N/A</td>
    </tr>
</table>

### Config-Form Elements

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

<table>
    <tr>
        <th>Name</th>
        <th>Required</th>
        <th>Description</th>
        <th>Default</th>
    </tr>
    <tr>
        <td>directory</td>
        <td><span class="tick" /></td>
        <td>
            A directory that contains any custom Soy, JavaScript and CSS files required to implement the view.
        </td>
        <td>N/A</td>
    </tr>
    <tr>
        <td>view</td>
        <td><span class="tick" /></td>
        <td>
            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.
            <p/>
            For more information about AUI please visit the <a href="http://docs.atlassian.com/aui/latest">sandbox</a>.
            For an a list of available Soy templates that you can use in your own configuration form, consult the
            <a href="https://bitbucket.org/atlassian/aui/src/5.8.14/src/soy/form.soy">source</a>. </td>
        <td>N/A</td>
    </tr>
</table>

## Simple Example

Here is an example `atlassian-plugin.xml` file containing just a repository hook.

```xml
<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.

```xml
<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](../../how-tos/repository-hooks.html#Examples).
