How to create a simple hook in Bitbucket Data Center and Server

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

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:

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

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:

The main page for Plugins on Bitbucket server are on the documentation below:


2. Creating the hook

Before you execute the manual procedure below, note that there is a plugin on Marketplace that helps you set this up (as opposed to doing so manually as outlined below):


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 Server 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. 

This number should always be something higher than 20 because the script that we ship needs to be executed first.

Simple Hook Message
echo "pre-receive message 30"
exit  0

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

Do not edit the post-receive.d/20_bitbucket_callback or pre-receive.d/20_bitbucket_callback files in these directories. This file must remain untouched and have full permissions for hooks to function. It is a good practice to have the user running Bitbucket Server own the pre or post-receive hook.

Troubleshooting

  • If a hook is not functioning one thing you can check is the application.xml file located in BITBUCKET_HOME/logs/support (this file is generated when you create a Support Zip) 

  • Make sure that the isExecutable element is true.  

  • If the script still doesn't run, you can always approach the troubleshooting by creating a simple file containing an echo just as described on the step #3 above.

  • If you are executing a command that the user running Stash/Bitbucket server doesn't have permission to, that will fail.

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:

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

Description

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, though strongly discouraged, to create a server side Git hook in your Bitbucket Server instance's file system. This page discusses the latter process.

ProductBitbucket
Last modified on May 23, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.