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://firstname.lastname@example.org: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.
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 : 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 : 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
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
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 email@example.com:/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
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://firstname.lastname@example.org: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://email@example.com:29418/l2mesh Creating a git remote called "gerrit" that maps to: ssh://firstname.lastname@example.org: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://email@example.com: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 firstname.lastname@example.org 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://email@example.com: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://firstname.lastname@example.org: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 email@example.com 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.