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 or , followed by the full path to the interpreter e.g. . If these are not specified, Bitbucket Server will use the default. Following this, you then specify your script.
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.
These variables are available when a script gets executed.
All hooks will have the following variables set.
|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: or|
|BB_IS_DRY_RUN||Whether it is a dry run. Value: or|
|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: or|
|BB_REPO_IS_PUBLIC||Whether the repository is public. Value: or|
|BB_BASE_URL||The Bitbucket Server 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: , , ,|
For merges, standard variables like 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, will return ).
|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: or|
|BB_FROM_REPO_IS_PUBLIC||Whether the from repository is public. Value: or|
|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. is ).|
|BB_MERGE_IS_CROSS_REPO||Whether the merge was cross-repository. Value: or|
|BB_MERGE_STRATEGY_ID||The strategy used for the merge. For example: , ,|
|BB_TO_REF||The target ref for the merge.|
|BB_TO_HASH||The hash of the target ref at the time it was merged.|
Hooks triggered in response to pull request merges will have standard variables, merge variables, and the additional variables below in their environment.
|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: , , , ,|
See also Registering and maintaining hook scripts.