Purpose

Bitbucket Server has two primary ways you can create a hook.

The recommended way is to create a Plugin Using our Java plugin development framework.

It is also possible, although strongly discouraged (due to possibly causing permissions and functionality issues), to create a server side Git hook in your Bitbucket DC/Server instance.

Solution

1. Using the Java plugin framework

There are two primary approaches to creating a pre-receive hook using the Java plugin development framework. 

The primary approach consists on implementing PreReceiveRepositoryHook. In this case, a standard configuration is required, and indeed this configuration panel will be present in all repositories in the Stash. This approach is documented here:

• Pre-Receive with configuration

Here is a blog post and a tutorial that further describe that approach:

• Hooked on Stash

• Stash Plugin Tutorial: Beer O'Clock Repository Hook

Another approach involves implementing the PreReceiveHook interface. This does not imply a configuration screen, although you can add one if you so desire that would be present only on certain repositories. The basics you would need to get implement just the hook (no-configuration) can be found:

• Pre-receive hook Plugin Module
  
  

2. Creating the hook

For Bitbucket versions below 8.0:

The steps below will focus on hooks created directly on the file system.

1) Navigate to a repository in a bitbucket instance:

Please see Identifying a repository's ID in Bitbucket Data Center if you aren't sure how to find this location. 

Bitbucket Server hooks are enabled and configured on a per repository basis so you will need to create your hook in each repositories hooks directory. 

2) Navigate to the directory of  pre-receive or post-receive hooks: 

Inside the hooks directory of a repository (on the server where Bitbucket is running)  you will find two directories called pre-receive.d and post-receive.d. A hook should be created in one of these two locations accordingly to your objectives. 

Pre-receive hooks are used to potentially block pushes to Bitbucket Server. An example might be to stop deletion of branches or limit force-pushes to personal branches. Pre-receive hooks do not fire when a pull-request is merged - for that, you may also want to implement a repository merge-check.

Post-receive hooks are invoked after a push has taken place. An example might be to notify a build server, such as Bamboo, that there are new commits on a branch to be built.

3) Create a file in the pre or post-receive directory

The number at the beginning of the file name will indicate the order your hook will be executed. If you have multiple hooks and you want them to happen in a specific order number them accordingly: 21_pre_receive, 22_pre_receive, 23_pre_receive and so on. 

echo "pre-receive message 30"
exit  0

This message will display in the clients command line "pre-receive message 30".

Troubleshooting

For Bitbucket version 8.0 and above:

It is no longer possible to create hook scripts directly on the file system. Instead, REST API must be used for this purpose.

First, you will need to create a global hook script, using the following endpoint:

• To create / update / delete a global hook script
  (POST /rest/api/latest/hook-scripts)

Next, the following endpoints must be used, to associate the hook script with a project, or a repository:

• To create / update / delete a project-level hook script
  (PUT /rest/api/latest/projects/{projectKey}/hook-scripts/{scriptId})
• To create / update / delete a repository-level hook script
  (PUT /rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/hook-scripts/{scriptId})

Related Content