Using repository hooks
Hooks let you to extend what Bitbucket 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 Server 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 Server 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 Server 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 Bitbucket Server 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 Server supported two types of post-receive hook:
- PostReceiveHooks used to map to Git's
post-receivehooks. They ran on the Bitbucket Server instance after a push. - AsyncPostReceiveRepositoryHooks, was executed by the Bitbucket Server 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):
- Go to Project settings > Hooks.
- 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):
- Go to Repository settings > Hooks.
- Use the drop menu to the right of the hook to set it.
- Inherited - uses the configuration set at the project level.
- Enabled - enforces the conditions of the hook.
- 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 Server 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.
Hook disabled, project level
| Hook disabled, repository level
|
Hook enabled, project level
| Hook enabled, repository level
|
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.
Hook enabled, project level
| Hook disabled, repository level
|
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.