Configuring External Hooks

After the installation has finished, the External Hook Add-on can be used to implement Pre Receive, Post Receive, and Merge Check hooks in a repository.

The configuration is a 3-step process:

• activate a preferred hook on repository settings,
• implement a bash script file with execute permissions in the Executable section and set up environment variables in the Positional parameters section, select Safe mode if required,
• enable the hook.

The details of the process are discussed in the following sections.

If you are not familiar how to connect to a server, send a file or set permissions to the file, follow this guide: Configuring Bitbucket Server.

Configuration #

This section describes the main steps of how to enable and configure a hook for a repository.

External Pre Receive Hook #

1. Go to Repository Settings > Hooks.

2. One item of the External Pre Receive Hook is present in the Pre receive section. Enable it with the drop menu to the right of the hook.

   

3. The External Pre Receive Hook panel appears on the screen next. Fill the empty fields with the required arguments and click Enable.

   

External Async Post Receive Hook #

1. Go to Repository Settings > Hooks

2. One item of the External Async Post Receive Hook is present in the Post receive section. Enable it with the dropdown menu to the right of the hook.

   

3. The External Async Post Receive Hook panel appears on the screen. Fill the empty fields with required arguments.

   

External Merge Check Hook #

1. Go to Repository Settings > Merge Check.

2. One item of the External Merge Check Hook is present in the Merge check section. Enable it with the drop menu to the right to the hook.

   

3. The External Merge Check Hook panel appears on the screen. Fill the empty fields with the required arguments.

   

Configuration Parameters #

The section describes how to specify the configuration parameters of a hook.

Executable #

The Executable must be either:

• an absolute path to a file with the execute permissions on the server, where Bitbucket is located,
• a path, that is relative to the <bitbucket-home-dir>/external-hooks or <bitbucket-home-dir>/shared/external-hooks (in case of Bitbucket DataCenter Edition) path (only with Safe mode activated).

The Bitbucket administrator can only set the Executable for security reasons. However, ordinary Bitbucket users can also set the executable if Safe mode is enabled.

Safe Mode #

Safe mode can be used by non-privileged users for specifying the path of the executable created by the administrator in the <bitbucket-home-dir>/external-hooks/ directory.

Note: Bitbucket DataCenter users must use <bitbucket-home-dir>/shared/external-hooks directory.

It’s highly recommended to set the Executable in Safe mode, as it takes away the administrator’s burden of configuring each repository manually.

Positional Parameters #

The positional parameters field in the configuration of a hook lets the individual set up positional command line arguments which will be passed to the executable.

They must be specified one per line and without any quotes.

The executable process will be provided with the set of environment variables: Environment Variables

NOTES:

Notes below applied only for Bitbucket version under 6.0.0.

• The Pre- and Post- Receive Hooks do not differ much, but keep in mind that any output produced by the post-receive hook will be silently ignored.

• When a user pushes local changes to a remote repository, they receive the hook output if the hook exits with a non-zero exit code.

See the CHANGELOG page for more information about the latest changes.

Next Step #

Visit the Common Use Cases page to learn practical cases about the implementation of the preceding types of hooks.