Using repository hooks

Pre-receive hooks

Pre-receive hooks allow you to control which commits go into your repository before pushes are committed or pull requests are merged. For example, a pre-receive hook can reject pushes to the repository if certain conditions are not fulfilled. It could prevent force pushes to the repository or check whether all commits contain a valid Jira application issue key.  

Default pre-receive hooks

Bitbucket comes with some pre-receive hooks installed by default that are disabled, but can be enabled at the project level for all repositories in a project, or for individual repositories.

The default hooks that come with Bitbucket are:

• Reject Force Push - rejects all force pushes to a repository.
• Verify Commit Signature - rejects commits and tags without a verified GPG signature.
• Verify Committer - rejects commits not committed by the user pushing to a repository.

Post-receive hooks

Post-receive hooks run after commits are processed, and are typically used to update external services or send notifications. For example, the Web Post Hooks Plugin can send a message to a chat client or notify a continuous integration server changes.

For releases prior to 5.0, Bitbucket supported two types of post-receive hook:

• PostReceiveHooks used to map to Git's post-receive hooks. They ran on the Bitbucket instance after a push.
• AsyncPostReceiveRepositoryHooks, was executed by the Bitbucket instance.

From 5.0 onwards, these are now both deprecated and have been replaced by: 

• PostRepositoryHooks, which gets called for both PR merge and post-receive.

Configure hooks for all repositories in a project

Enabling (or disabling) hooks at the project level changes hooks for repositories set to inherit project settings. If you previously changed hooks for an individual repository, that repository's configuration will not change when configuring hooks at the project level.

To enable (or disable) hooks for repositories in a project (requires project admin permissions):

1. Go to Project settings > Hooks.
2. Click the toggle by the hook to enable (or disable) it.

Hooks for repositories set to Inherited in the project will now reflect this new configuration. Hooks explicitly configured at the repository level will not be affected. 

Configure hooks for an individual repository

Configuring hooks at the repository level will override any checks configured at the project level. If you have not configured hooks for an individual repository it will inherit hooks configured at the project level.

To enable (or disable) hooks for a single repository (requires repository admin permissions):

1. Go to Repository settings > Hooks.
2. Use the drop menu to the right of the hook to set it.
   1. Inherited - uses the configuration set at the project level.
   2. Enabled - enforces the conditions of the hook.
   3. Disabled - ignores the conditions of the hook.

Once set, any changes made to hook configuration at the project level will be ignored for this repository because it was changed independent of the project configuration.

Inherited hook configurations

By default, Bitbucket comes with hooks disabled at the project and repository level. Unless hooks were configured at the repository level, enabling or disabling hooks at the project level inherits the configuration at the repository level. 

For example, if you enabled the Reject Force Push hook for a project, and a repository hook configuration was unchanged, each repository would have the Reject Force Push hook enabled.

Now suppose you decide that the Reject Force Push hook isn't appropriate for one specific repository. You can change that individual repository's hooks independent of how it's configured at the project level. Any changes made to hook configuration at the project level for the Reject Force Push will be ignored for this repository, because it was changed independent of the project configuration.

Add a new hook

Additional hooks can be installed by system administrators and can also be enabled for all repositories in a project, or for individual repositories.

To add hooks from the Atlassian Marketplace (requires system admin permission):

1. Go to Project settings > Hooks.
2. Click Add hook.
3. Search for a hook to add, and click Install. 

Once you add a new hook, you can enable (or disable) it in the same way as the default hooks.

Create a hook

You can also write your own hooks. Here are some useful resources to help you get started. 

• Repository hooks
• Repository hook plugin module
• Blog post about hooks for Bitbucket
• Video demo on how to get started on Bitbucket hooks