gerrit with jenkins : installation and configuration

The review and project management for Git based projects is installed on a virgin Debian GNU/Linux wheezy. Developers of l2mesh must submit patchs to the git repository to gerrit:

$ git review
remote: Resolving deltas: 100% (1/1)
remote: Processing changes: new: 1, done
To ssh://loic@gerrit.the.re:29418/l2mesh
 * [new branch]      HEAD -> refs/publish/master/master

Gerrit is bound to jenkins : it will run tests on the patch to be reviewed and let gerrit know if it succeeds. If a developer reviews the patch positively, it can be merged into the repository.

instance creation

An openstack instance is created from a virgin Debian GNU/Linux wheezy

nova boot --image 'Wheezy' --flavor e.1-cpu.10GB-disk.1GB-ram --key_name loic --availability_zone=bm0002 --poll gerrit

gerrit installation and configuration

Gerrit is installed from the unofficial package

apt-get install openjdk-6-jre
wget http://users.unix-heaven.org/~dnaeon/gerrit-debian/gerrit_2.4.2-1_all.deb
dpkg -i gerrit_2.4.2-1_all.deb

and configured as follows:

Setting up gerrit (2.4.2-1) ...
Starting Gerrit Code Review : gerrit
No Gerrit site found. Will Initialize Gerrit first...

*** Gerrit Code Review 2.4.2
***

Create '/var/lib/gerrit/review_site' [Y/n]?

*** Git Repositories
***

Location of Git repositories   [git]:

*** SQL Database
***

Database server type           [H2/?]:

*** User Authentication
***

Authentication method          [OPENID/?]: http
Get username from custom HTTP header [y/N]?
SSO logout URL                 :

*** Email Delivery
***

SMTP server hostname           [localhost]:
SMTP server port               [(default)]:
SMTP encryption                [NONE/?]:
SMTP username                  :

*** Container Process
***

Run as                         [gerrit]:
Java runtime                   [/usr/lib/jvm/java-6-openjdk-amd64/jre]:
Copy gerrit.war to /var/lib/gerrit/review_site/bin/gerrit.war [Y/n]?
Copying gerrit.war to /var/lib/gerrit/review_site/bin/gerrit.war

*** SSH Daemon
***

Listen on address              [*]:
Listen on port                 [29418]:

Gerrit Code Review is not shipped with Bouncy Castle Crypto v144
  If available, Gerrit can take advantage of features
  in the library, but will also function without it.
Download and install it now [Y/n]?
Downloading http://www.bouncycastle.org/download/bcprov-jdk16-144.jar ... OK
Checksum bcprov-jdk16-144.jar OK
Generating SSH host key ... rsa... dsa... done

*** HTTP Daemon
***

Behind reverse proxy           [y/N]? y
Proxy uses SSL (https://)      [y/N]?
Subdirectory on proxy server   [/]: /gerrit/
Listen on address              [*]:
Listen on port                 [8081]:
Executing /var/lib/gerrit/review_site/bin/gerrit.sh start
Starting Gerrit Code Review: OK
Waiting for server to start ... OK
Opening browser ...
Please open a browser and go to http://gerrit.novalocal:8081/gerrit/#/admin/projects/

The proposed default [git] is the subdirectory of /var/lib/gerrit/review_site where the git repositories are expected to be found. The default H2 is chosen because the configuration for MySQL did not work (for an unknown reason). Since the machine running gerrit only has a private IP, the http server is configured to run behind a reverse proxy that will be configured on another machine and proxy all requests going to /gerrit/ ( note the trailing and leading /, both are mandatory ).
If something goes wrong, the package configuration and installation can be run again as follows:

/etc/init.d/gerrit stop
apt-get remove --purge gerrit
rm -fr /var/lib/gerrit/review_site
dpkg -i gerrit_2.4.2-1_all.deb

Gerrit can be launched manually with

/var/lib/gerrit/review_site/bin/gerrit.sh start

and the error logs are in the /var/lib/gerrit/review_site/logs directory:

root@gerrit:~# grep Exception /var/lib/gerrit/review_site/logs/error_log |
   tail -1
Caused by: java.net.URISyntaxException: Illegal character in port number
   at index 19: proxy-http://A:8081gerrit/

reverse proxy and authentication

An apache server is configured to reverse proxy all requests going to /gerrit/ to the gerrit http server:

<VirtualHost *:80>
...
 ProxyRequests Off
 ProxyVia Off
 ProxyPreserveHost On

 <Proxy *>
  Order deny,allow
  Allow from all
 </Proxy>
 ProxyPass /gerrit/ http://gerrit.novalocal:8081/gerrit/
...
</VirtualHost>

Alternatively, the reverse proxy can be configured using RewriteEngine with:

RewriteRule    ^/gerrit/(.*)$   http://gerrit.novalocal:8081/gerrit/$1 [P,QSA,L]

Gerrit will expect users to be authentified. This is done, on the reverse proxy virtual host, by requiring a user when accessing the /gerrit/login/ location.

<VirtualHost *:80>
...
 <Location /gerrit/login/>
  AuthType Basic
  AuthName "Gerrit Code Review"
  Require valid-user
  AuthUserFile '/etc/apache2/gerrit.htpasswd'
 </Location>
...
</VirtualHost>

Users matching the names used in other sub systems such as redmine or jenkins can be created with

htpasswd -c /etc/apache2/gerrit.htpasswd loic
New password:
Re-type new password:
Adding password for user loic

Assuming the web site where the reverse proxy was installed is redmine.the.re, browsing the http://redmine.the.re/gerrit/ URL will display:

and after a successfull authentication the following gerrit dashboard will show:

The first user to register has admin rights. The web interface does not allow to create projects : such operations are done by interacting with the gerrit ssh server. The gerrit ssh server will only accept requests from users it knows and will require a ssh public key to let them in. The ssh public key for loic is registered in the settings page:

which shows as follows when it is accepted:

To check that it works as expected, run the following from the machine on which gerrit is installed, assuming ssh agent forwarding was enabled when connecting to it ( ssh -A ):

root@gerrit:# ssh -p 29418 loic@localhost gerrit version
gerrit version 2.4.2

mail confirmation

When a user set his email address in the gerrit web interface, a confirmation is sent to validate it. The user email will not be accepted until the URL sent in the confirmation email is visited. For instance:

Welcome to Gerrit Code Review at gerrit.novalocal.

To add a verified email address to your user account, please
click on the following link while signed in as Loic Dachary:

$email.gerritUrl#/VE/LwYyrz8r36yAAAQ/M/LWWJZ2Mh97Q686e46DUA==$MTAwMDAwMDpsb2ljQGRhY2hhcnkub3Jn

Note that $email.gerritUrl above must be replaced by http://redmine.the.re/gerrit/. After validation another email can be added.

create a new gerrit project

The project is created using the gerrit create-project command.

ssh -p 29418 loic@localhost gerrit create-project l2mesh --description "'l2mesh is a tinc based virtual switch, implemented as a puppet module. It creates a new ethernet interface on the machine and \
connects it to the switch'"

Note that the description is enclosed in single quotes enclosed in double quotes.
It can also be imported independently with:

rsync -avH root@redmine.the.re:/srv/repos/git/l2mesh.git/ \
   /var/lib/gerrit/review_site/git/l2mesh.git/
chown -R gerrit:gerrit /var/lib/gerrit/review_site/git/l2mesh.git

and will show immediately in the web interface:

setup gerrit client side

The git-review package contains the necessary components to setup a clone to submit reviews to gerrit. The basic idea is that a push is replaced by a review which submits a review to gerrit. The .gitreview file at the root of the git repository is created to contain the address of the gerrit server.

root@gerrit:/tmp# git clone ssh://loic@gerrit.novalocal:29418/l2mesh.git
Cloning into 'l2mesh'...
remote: Counting objects: 105, done
remote: Finding sources: 100% (105/105)
Receiving objects: 100% (105/105), 73.32 KiB, done.
remote: Total 105 (delta 0), reused 0 (delta 0)
root@gerrit:/tmp# cd l2mesh
root@gerrit:/tmp/l2mesh# cat .gitreview
[gerrit]
host=gerrit.novalocal
port=29418
project=l2mesh

git is instructed to take it into account

root@gerrit:/tmp/l2mesh# git review -s
Trying again with ssh://loic@gerrit.novalocal:29418/l2mesh
Creating a git remote called "gerrit" that maps to:
        ssh://loic@gerrit.novalocal:29418/l2mesh

a test modification is submitted for review:

root@gerrit:/tmp/l2mesh# echo yes > TEST
root@gerrit:/tmp/l2mesh# git add TEST
root@gerrit:/tmp/l2mesh# git commit -m 'test comment' TEST
[master 83ed22b] test comment
 Committer: root 
 1 file changed, 1 insertion(+)
 create mode 100644 TEST
root@gerrit:/tmp/l2mesh# git review
remote: Resolving deltas: 100% (1/1)
remote: Processing changes: new: 1, done
To ssh://loic@gerrit.novalocal:29418/l2mesh
 * [new branch]      HEAD -> refs/publish/master/master
root@gerrit:/tmp/l2mesh#

and the web interface should now display on the user dashboard:

binding jenkins and gerrit

Select Gerrit Trigger after filtering with gerrit in the plugin manager.

If the installation is successfull the following page shows:

And when going back to the jenkins home page the Query and Trigger Gerrit Patches menu entry has been added to the left menu.

Configure gerrit using /jenkins/gerrit-trigger/

A jenkins user is created in gerrit

root@jenkins ~# ssh -p 29418 loic@gerrit.novalocal gerrit create-account \
  --ssh-key - jenkins < /usr/share/tomcat6/.ssh/id_rsa.pub

It must be able to clone the l2mesh repository from the jenkins machine.

# su - tomcat6
tomcat6@jenkins:/tmp$ git clone ssh://jenkins@gerrit.novalocal:29418/l2mesh.git 
Cloning into l2mesh...
The authenticity of host '[gerrit.novalocal]:29418 ([10.145.0.15]:29418)' can't be established.
RSA key fingerprint is ba:52:ed:8b:23:19:62:de:41:7c:17:84:e9:31:c6:c0.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '[gerrit.novalocal]:29418,[10.145.0.15]:29418' (RSA) to the list of known hosts.
remote: Counting objects: 105, done
remote: Finding sources: 100% (105/105)
remote: Total 105 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (105/105), 73.32 KiB, done.

The jenkins user is then used to configure Gerrit Trigger as shown in the screenshot below. The Test Connection button shows it works by displaying success to the left.

The Restart button at the bottom of the page, in the Control box must be clicked before clicking Save.

If the following error shows, click Restart and Save again.

The l2mesh project is configured by clicking both Advanced buttons to display the required input boxes and following the Gerrit Trigger instructions ( Usage with the Git Plugin section ).

Jenkins is required to monitor the ssh://jenkins@gerrit.novalocal:29418/l2mesh.git repository and to checkout the reference $GERRIT_REFSPEC from the branch $GERRIT_MASTER.

The strategy to poll the repository is set to Gerrit Trigger in the Choosing strategy select box.

setting gerrit permissions

The jenkins user is expected to Verify a patch and all registered users are expectd to review them and be able to give them a +2. When a patch is reviewed, the registered users are expected to Submit the patch (i.e. push it to the git repository). The default gerrit permissions are too restrictive and need to be relaxed. The jenkins user is added to the group of Non-Interactive users.

The gerrit projects are organized in a hierarchy that where permissions are inherited. The All-Projects project is the root of this hierarchy and its permissions are modified so that they are inherited by all children projects.

The permissions to Review, Submit and Verify need to be adjusted for the refs/heads/* Reference. The Submit and Verify permissions must to be added.

The Non-Interactive and Registered Users can then be adjusted to match the requirements.

When it is finished the Save changes button at the bottom of the page must be clicked.

triggering jenkins manually

The Query and Trigger Gerrit Patches menu entry to the left of the jenkins home page allows to manually trigger jenkins on designated patches. Looking for l2mesh in the search box will display all the pending reviews.

after the Trigger Selected button is clicked, the corresponding jenkins job is run and its progress shows to the left.

When the test is successfull, jenkins will notify jenkins with

ssh -p 29418 jenkins@gerrit.novalocal gerrit approve 1,1 \
  --verified 1 --code-review 0

and the result will show in the web interface, in the Verified columns (jenkins shows as Anonymous Coward because its name has not been set).

The user Vincent-Xavier Jumel was created ( in the same way the user loic was created above ) and is expected to review the code ( this is why the Need Code-Review shows at the bottom of the screenshot above. After Vincent-Xavier Jumel review with a +2, the default gerrit requirements for a patch to be pushed are met and the Submit Patch button shows.

After clicking on the Submit Patch button, the status of the review changes to merged.