Installing the hooks

The hooks infrastructure is separatede in two parts, the hook dispatcher, and the actual hooks.

The dispatcher is in charge of deciding which hooks to run for each event, and gives the final review on the change. The hooks themselves are the ones that actually do checks (or any other action needed) and where the actual login you would want to implement resides.

Install the dispatcher

To install the hook dispatcher just add it to the gerrit configuration as hook for any events you want to create hooks for, for example, soft linking it in $review_site/hooks/ like this:

[root@gerrit ~]# ll /home/gerrit2/review_site/hooks/
change-abandoned -> /home/gerrit2/review_site/hooks/hook-dispatcher
change-merged -> /home/gerrit2/review_site/hooks/hook-dispatcher
comment-added -> /home/gerrit2/review_site/hooks/hook-dispatcher
patchset-created -> /home/gerrit2/review_site/hooks/hook-dispatcher

That will allow you to manage the events ‘change-abandoned’, ‘change-merged’, ‘comment-added’ and ‘patchset-created’.

Alternatively you can configure gerrit to use the hook-dispatcher from gerrit.conf (see the gerrit config help)

Note: Make sure it’s executable

Install the hooks

Once the dispatcher is in place, you can add per-project hooks, those are just executable scripts, you can use anything you like, though I suggest taking a look at the libs here, that already handle most of the hustle for you.

So to install a hook, just put it under the $review_site/git/$project.git/hooks/ directory with the name:

$event.[$chain.]$name

For now, we can ignore the $chain, it’s explained later in the Execution flow: chains section. The $name is any string you want to identify the hook you just installed.

I recommend keeping all the hooks you install in the same directory, for example, under $review_site/hooks/custom_hooks and just create soft-links to them on the $review_site/git/$project/hooks directory for ease of management and maintenance.

For example, the current hooks for the ovirt-engine oVirt project:

change-abandoned.update_tracker -> update_tracker
change-merged.set_MODIFIED -> /home/gerrit2/review_site/hooks/custom_hooks/change-merged.set_MODIFIED
change-merged.update_tracker -> update_tracker
comment-added.propagate_review_values -> /home/gerrit2/review_site/hooks/custom_hooks/comment-added.propagate_review_values
patchset-created.bz.0.has_bug_url -> /home/gerrit2/review_site/hooks/custom_hooks/patchset-created.bz.0.has_bug_url
patchset-created.bz.1.is_public -> /home/gerrit2/review_site/hooks/custom_hooks/patchset-created.bz.1.is_public
patchset-created.bz.2.correct_product -> /home/gerrit2/review_site/hooks/custom_hooks/patchset-created.bz.2.correct_product
patchset-created.bz.3.correct_target_milestone -> /home/gerrit2/review_site/hooks/custom_hooks/patchset-created.bz.3.correct_target_milestone
patchset-created.bz.98.set_POST -> /home/gerrit2/review_site/hooks/custom_hooks/patchset-created.bz.98.set_POST
patchset-created.bz.99.review_ok -> /home/gerrit2/review_site/hooks/custom_hooks/patchset-created.bz.99.review_ok
patchset-created.update_tracker -> update_tracker
patchset-created.warn_if_not_merged_to_previous_branch -> /home/gerrit2/review_site/hooks/custom_hooks/patchset-created.warn_if_not_merged_to_previous_branch
update_tracker -> /home/gerrit2/review_site/hooks/custom_hooks/update_tracker

Execution flow: chains

So as was said before, when you install a hook you can optionally specify a $chain in it’s name. That is to allow a better control of the execution flow. You can find a detailed description at the JUC 2014 presentation.

The key idea is that using a chain of hooks, you can control with the return code if the chain is broken and skip the execution of the rest of the chain, jumping directly to the next.

Check the hook_dispatcher.run_hooks docs for more details on the return codes.