Writing hook scripts

Overview

Hook scripts are programs that run automatically every time a particular event occurs in a Git repository. You can use them to customize Git’s internal behavior and trigger customizable actions at key points in the development life cycle. This page describes how to write them, to add a new script to the system follow the guide for registering and maintaining hook scripts. You can write hook scripts in any scripting language. Their format is generally a first line consisting of a shabang or #!, followed by the full path to the interpreter e.g. #!/bin/bash. If these are not specified, Bitbucket Data Center will use the default. Following this, you then specify your script.

Executing hook scripts

Scripts are executed on the system. The system then listens to the output and the return code. If the script is a pre-style script it can veto the registered action. If it is a post-stye script then any non-zero exit code will be ignored.

Environment variables

These variables are available when a script gets executed.

Standard variables

All hooks will have the following variables set.

Variable name	Description
BB_HOOK_TRIGGER_ID	The action that triggered the hook. For example: branch-create, pull-request-merge, or push.
BB_HOOK_TYPE	Whether it is a pre or post-style hook. Value: `PRE` or `POST`
BB_IS_DRY_RUN	Whether it is a dry run. Value: `true` or `false`
BB_PROJECT_KEY	The repository's project key.
BB_REPO_SLUG	The repository slug.
BB_REPO_IS_FORK	Whether the repository is a fork. Value: `true` or `false`
BB_REPO_IS_PUBLIC	Whether the repository is public. Value: `true` or `false`
BB_BASE_URL	The Bitbucket Data Center base URL.
BB_REPO_CLONE_SSH	The SSH URL for cloning the repository. If SSH clones are disabled this does not need to be set.
BB_REPO_CLONE_HTTP	The HTTP URL to clone the repository. If HTTP clones are disabled this does not need to be set.
BB_USER_NAME	The username of the user that triggered the script.
BB_USER_DISPLAY_NAME	The full name of the user that triggered the script.
BB_USER_EMAIL	The email address of the user that triggered the script.
BB_USER_PERMISSION	The highest permission level for the repository or system of the user that triggered the script. For example: `REPO_WRITE`, `REPO_ADMIN`, `ADMIN`, `SYS_ADMIN`

Merge variables

For merges, standard variables like BB_REPO_SLUG can be applied to the "to" side of the merge. Details about the branches involved in the merge and other merge details are given in the following environment variables. The "to" ref/hash will also be given via stdin unless it is a dry run (if it is, BB_IS_DRY_RUN will return true).

Variable name	Description
BB_FROM_PROJECT_KEY	The repository's project key.
BB_FROM_REPO_SLUG	The repository slug.
BB_FROM_REPO_IS_FORK	Whether the repository is a fork. Value: `true` or `false`
BB_FROM_REPO_IS_PUBLIC	Whether the from repository is public. Value: `true` or `false`
BB_FROM_REF	The source ref for the merge.
BB_FROM_HASH	The hash of the source ref at the time it was merged.
BB_FROM_REPO_CLONE_SSH	The SSH URL for cloning the repository. If SSH clones are disabled this does not need to be set.
BB_FROM_REPO_CLONE_HTTP	The HTTP URL to clone the repository. If HTTP clones are disabled this does not need to be set.
BB_MERGE_HASH	The merge commit hash. If it is a dry run this will be empty (i.e. `BB_IS_DRY_RUN` is `true`).
BB_MERGE_IS_CROSS_REPO	Whether the merge was cross-repository. Value: `true` or `false`
BB_MERGE_STRATEGY_ID	The strategy used for the merge. For example: `ff`, `rebase-ff-only`, `squash`
BB_TO_REF	The target ref for the merge.
BB_TO_HASH	The hash of the target ref at the time it was merged.

Pull request environment variables

Hooks triggered in response to pull request merges will have standard variables, merge variables, and the additional variables below in their environment.

Variable name	description
BB_PULL_REQUEST_ID	The pull request ID (scoped to the repository).
BB_PULL_REQUEST_AUTHOR_USER_NAME	The username of the pull request author.
BB_PULL_REQUEST_AUTHOR_USER_DISPLAY_NAME	The full name of the pull request author.
BB_PULL_REQUEST_AUTHOR_USER_EMAIL	The email address of the pull request author.
BB_PULL_REQUEST_AUTHOR_USER_PERMISSION	The highest permission level of pull request author for the target repository or system For example: `REPO_READ`, `REPO_WRITE`, `REPO_ADMIN`, `ADMIN`, `SYS_ADMIN`