How to create a simple hook in Bitbucket Data Center and Server
プラットフォームについて: サーバーと Data Center のみ。この記事は、サーバーおよび Data Center プラットフォームのアトラシアン製品にのみ適用されます。
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.
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
Inside the hooks directory of a repository (on the server where Bitbucket is running) you will find two directories called
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
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.
echo "pre-receive message 30" exit 0
This message will display in the clients command line "
pre-receive message 30".
pre-receive.d/20_bitbucket_callbackfiles 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.
If a hook is not functioning one thing you can check is the
application.xml filelocated in
Make sure that the
If the script still doesn't run, you can always approach the troubleshooting by creating a simple file containing an
echojust 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:
- To create / update / delete a global hook script
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
- To create / update / delete a repository-level hook script