Last updatedApr 9, 2019

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 Server 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 nameDescription
BB_HOOK_TRIGGER_IDThe action that triggered the hook. For example: branch-create, pull-request-merge, or push.
BB_HOOK_TYPEWhether it is a pre or post-style hook. Value: PRE or POST
BB_IS_DRY_RUNWhether it is a dry run. Value: true or false
BB_PROJECT_KEYThe repository's project key.
BB_REPO_SLUGThe repository slug.
BB_REPO_IS_FORKWhether the repository is a fork. Value: true or false
BB_REPO_IS_PUBLICWhether the repository is public. Value: true or false
BB_BASE_URLThe Bitbucket Server base URL.
BB_REPO_CLONE_SSHThe SSH URL for cloning the repository. If SSH clones are disabled this does not need to be set.
BB_REPO_CLONE_HTTPThe HTTP URL to clone the repository. If HTTP clones are disabled this does not need to be set.
BB_USER_NAMEThe username of the user that triggered the script.
BB_USER_DISPLAY_NAMEThe full name of the user that triggered the script.
BB_USER_EMAILThe email address of the user that triggered the script.
BB_USER_PERMISSIONThe 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 nameDescription
BB_FROM_PROJECT_KEYThe repository's project key.
BB_FROM_REPO_SLUGThe repository slug.
BB_FROM_REPO_IS_FORKWhether the repository is a fork. Value: true or false
BB_FROM_REPO_IS_PUBLICWhether the from repository is public. Value: true or false
BB_FROM_REFThe source ref for the merge.
BB_FROM_HASHThe hash of the source ref at the time it was merged.
BB_FROM_REPO_CLONE_SSHThe SSH URL for cloning the repository. If SSH clones are disabled this does not need to be set.
BB_FROM_REPO_CLONE_HTTPThe HTTP URL to clone the repository. If HTTP clones are disabled this does not need to be set.
BB_MERGE_HASHThe 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_REPOWhether the merge was cross-repository. Value: true or false
BB_MERGE_STRATEGY_IDThe strategy used for the merge. For example: ff, rebase-ff-only, squash
BB_TO_REFThe target ref for the merge.
BB_TO_HASHThe 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 namedescription
BB_PULL_REQUEST_IDThe pull request ID (scoped to the repository).
BB_PULL_REQUEST_AUTHOR_USER_NAMEThe username of the pull request author.
BB_PULL_REQUEST_AUTHOR_USER_DISPLAY_NAMEThe full name of the pull request author.
BB_PULL_REQUEST_AUTHOR_USER_EMAILThe email address of the pull request author.
BB_PULL_REQUEST_AUTHOR_USER_PERMISSIONThe highest permission level of pull request author for the target repository or system For example: REPO_READ, REPO_WRITE, REPO_ADMIN, ADMIN, SYS_ADMIN

Notes

See also Registering and maintaining hook scripts.