Using repository hooks
Hooks let you to extend what Bitbucket Data Center and Server does every time a repository changes, allow you to customize your team's workflow, and enable you to integrate with other systems.
You can configure a hook to run automatically every time a particular event occurs in a repository, for instance when code is pushed or a pull request is merged.
Bitbucket supports two types of hooks, pre-receive and post-receive hooks. Hooks are installed by system administrators and can be enabled for all repositories in a project, or for an individual repository.
On this page:
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.
The Verify Committer hook uses the mappings in the file to verify commits, and based on how this file has been set up in your repository, multiple Git committers may be associated with a single Bitbucket user account.Git .mailmap
When using this hook, we recommend that you use Branch permissions (available in Project and Repository settings) to prevent changes without pull requests to your base/production branch. This will allow you to review and prevent unwanted changes to your Git.mailmap file.
You can also use the Push log page (available in Repository settings) to identify committers. Note that this log doesn’t use mappings from the Git .mailmap file.
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-receivehooks. 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:
- Repository hook plugin module, which gets called for both PR merge and post-receive.
Configure hooks for all repositories in a project
By default, hook settings from the project level are inherited by the repositories. Repository admins can either set a hook to inherit the project-level setting or override it (by enabling or disabling the hook at the repository-level).
Later when you modify a project-level hook (enable or disable a hook), only hooks in repositories that are set to inherit the project-level setting change to match the project-level hooks. Hooks that've been set to override project-level settings will not change.
Starting from Bitbucket 8.10, project admins can also restrict repository-level customization of a hook. Note that when you restrict changes, any custom settings saved at the repository-level for that hook are deleted and the hook inherits project settings.
To enable (or disable) hooks for repositories in a project (requires project admin permissions):
- Go to Project settings > Hooks.
- Select More actions ... > Enable or Disable.
- Optional: To disable repository-level customization, select More actions ... > Don't allow.
Configure hooks for an individual repository
If your project admin hasn't restricted repository-level customization for a hook, you can configure it to override the project-level setting (enabled or disabled) or set it to inherit the project-level setting.
To enable (or disable) hooks for a single repository (requires repository admin permissions):
- Go to Repository settings > Hooks.
- Select More actions ... >
- Inherit from project, to use the project-level setting
- Enable or Disable to override the project-level setting
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):
- Go to Project settings > Hooks.
- Click Add hook.
- 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.