Tutorial for Gerrit administrators

Introduction

Gerrit is a Git server but since it uses JGit instead of standard Git, it doesn't support the standard Git hooks. It supports its own hooks instead.

Git::Hooks supports just three of the many Gerrit hooks so far: ref-update, patchset-created, and draft-published. The first one is much like the standard hooks pre-receive and update in that it can reject pushes when the commits being pushed don't comply. However, since Gerrit's revision process takes place before the commits are integrated, it's more useful to enable just the other two.

First, you have to create the same driver script as described for the server.

Then we must create the symlinks from the hook names to the driver script. However, in Gerrit there's a single hooks directory per server, instead of one per repository. Normally, when you install Gerrit, the hooks directory isn't created. It should be created below the Gerrit's site directory. Create it and the two symlinks like so:

$ cd .../gerrit-site
$ mkdir hooks
$ cd hooks
$ ln -s /usr/local/bin/githooks.pl patchset-created
$ ln -s /usr/local/bin/githooks.pl draft-published

The patchset-created hook is invoked when you push a patchset to Gerrit for revision, but Git::Hooks only enable it for non-draft patchsets, because draft patchsets can only be reviewed by their onwners and invited reviewers. The draft-published hook is invoked when you publish a draft-patchset. Both hooks run asynchronously so that they can't reject the push. Instead, they review the patchset as a normal reviewer would, casting a positive or negative vote, depending on the result of the checks made by the enabled plugins.

All the (standard) Git::Hooks plugins that attach to the pre-receive and update hooks also attach themselves to both the patchset-created and the draft-published hooks, so that you can use the same configuration we did above.

You have to do a little extra configuration in the githooks.gerrit section:

[githooks "gerrit"]
        url  = https://gerrit.cpqd.com.br
        username = gerrit
        password = a-very-large-and-difficult-to-crack-password
        votes-to-approve = Verification+1
        votes-to-reject = Verification-1

The three options url, username, and password tell where to connect to Gerrit and with which user's credentials. This is the user that will appear to be making comments and reviewing the patchsets.

Then you have to tell Git::Hooks how it should vote to approve and to reject a change using the options votes-to-approve and votes-to-reject. In the example above you tell Git::Hooks to cast a +1 in the Verification label to approve the change and to cast a -1 in the same label to reject it. You may cast multiple votes in multiple labels by separating the vote specifications with commas.

Gerrit has a notion of a hierarchy of repositories (called 'projects' in Gerrit). Gerrit's own configuration uses this hierarchy so that child repositories inherit their ancestor's configuration. Git's own configuration mechanism has no such notion, but you can fake it using the same include mechanism discussed above. But you have to do it manually, though.