Using repository hooks
Hooks in Bitbucket Server provide a way to customize a team's workflow and integrate with other systems. Bitbucket Server currently supports two types of hooks, pre and post-receive.
Administrators can see the hooks that are available in Bitbucket Server by going to Settings > Hooks for a Bitbucket Server repository. Once installed, hooks are available across all repositories in a Bitbucket Server instance, but are enabled separately on each repository in a project.
Click the 'pen' icon beside the name of a hook to edit configuration details for the hook.
Bitbucket Server currently ships with the following hooks:
- Reject Force Push – block all Git force pushes (
git push -- force).
- HipChat Push Notifications – send a message to a HipChat room when someone pushes to the repository.
The first hook to run when handling a push from a client is the pre-receive hook. It can reject pushes to the repository if certain conditions are not fulfilled. You can use this hook to prevent force pushes to the repository or check whether all commits contain a valid JIRA application issue key.
The post-receive hook runs after the commits have been processed and can be used to update other services or notify users. For example this post-receive hook could be used to send a message to a chat server or notify a continuous integration server such as Atlassian Bamboo of the newly pushed changes.
Bitbucket Server supports two types of post-receive hook:
- PostReceiveHooks map to Git's
post-receivehooks. They run on the Bitbucket Server instance after a push.
- AsyncPostReceiveRepositoryHooks, executed by the Bitbucket Server instance.
Note that a Git PostReceiveHook won't be triggered after a pull request merge. The mechanism that performs the pull request merge is actually based on a
post-receive hooks. To trigger functionality based on a pull request merge, you should write an AsyncPostReceiveRepositoryHook for the Bitbucket Server repository.
Getting hooks from the Atlassian Marketplace
A number of hooks are available from the Atlassian Marketplace. You can find and install these from within Bitbucket Server – simply use the Add hook button on the hooks settings page to view available hooks from the marketplace. See Managing add-ons for details.
Creating your own hooks
Developers can write receive hook plugins for Bitbucket Server using a simple API that provides a simple way to create a configuration interface, and stores the hook's configuration settings on a per-repository basis.
For information about how to write your own hooks please see the Bitbucket Server developer docs.
In particular, the Repository hook plugin module page will be helpful.
See too this blog post about hooks for Bitbucket Server: http://blogs.atlassian.com/2013/03/stash-git-hooks-api/
For a quick video demo on how to get started on Bitbucket Server hooks: https://developer.atlassian.com/blog/2015/01/beer-o-clock-stash-plugin-tutorial/