Diffusion User Guide: Commit Hooks

Phabricator User Documentation (Application User Guides)

Guide to commit hooks in hosted repositories.

Overview

Phabricator installs pre-receive/pre-commit hooks in hosted repositories automatically. They enforce a few rules automatically (like preventing dangerous changes unless a repository is configured to allow them). They can also enforce more complex rules via Herald, using the "Commit Hook: Branches/Tags/Bookmarks" and "Commit Hook: Commit Content" rule types.

Herald rules are flexible, and can express many of the most common hooks that are often installed on repositories (like protecting branches, restricting access to repositories, and requiring review).

However, if Herald isn't powerful enough to enforce everything you want to check, you can install additional custom hooks. These work mostly like normal hooks, but with a few differences.

Installing Custom Hooks

With hosted repositories, you can install hooks by dropping them into the relevant directory of the repository on disk:

• SVN Put hooks in hooks/pre-commit-phabricator.d/.
• Git Put hooks in hooks/pre-receive-phabricator.d/.
• Mercurial Phabricator does not currently support custom hooks in Mercurial.

These hooks act like normal pre-commit or pre-receive hooks:

• Executables in these directories will be run one at a time, in alphabetical order.
• They'll be passed the arguments and environment that normal hooks are passed.
• They should emit output and return codes like normal hooks do.
• These hooks will run only after all the Herald rules have passed and Phabricator is otherwise ready to accept the commit or push.

These additional variables will be available in the environment, in addition to the variables the VCS normally provides:

• PHABRICATOR_REPOSITORY The PHID of the repository the hook is executing for.
• PHABRICATOR_USER The Phabricator username that the session is authenticated under.
• PHABRICATOR_REMOTE_ADDRESS The connection's remote address (that is, the IP address of whoever is pushing or committing).
• PHABRICATOR_REMOTE_PROTOCOL The protocol the connection is using (for example, "ssh" or "http").