Using repository hooks

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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.

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:

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

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.

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):

  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. 

Last modified on Oct 27, 2022

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.