Howto Gerrit

Installation
Configuration avancée
- Reverse Proxy
- Authentification LDAP via Apache
Monitoring
Créer un utilisateur Gerrit via SSH
FAQ
- Erreur de login

Documentation : https://gerrit-documentation.storage.googleapis.com/Documentation/2.13.7/index.html

Gerrit est un logiciel libre de revue de code s’appuyant sur GIT. Il permet de lire, approuver ou rejeter les modifications d’un code source via une interface web.

Installation

Les pré-requis sont d’avoir une JRE en version 7 minimum et un serveur SQL. Nous conseillons d’utiliser openjdk-7-jre (ou openjdk-8-jre) et MySQL.

# apt install default-jre

Création de l’utilisateur Unix et MySQL

# adduser --disabled-password gerrit
# mysql

mysql> CREATE USER 'gerrit'@'localhost' IDENTIFIED BY 'PASSWORD';
mysql> CREATE DATABASE gerrit;
mysql> GRANT ALL ON gerrit.* TO 'gerrit'@'localhost';

Téléchargement du .war

# sudo -iu gerrit
$ wget https://www.gerritcodereview.com/download/gerrit-2.13.7.war -O gerrit.war

Initialiser la configuration

$ java -jar gerrit.war init -d /home/gerrit

Une série de questions vous sera posée pour initialiser la configuration. On pourra répondre ? pour avoir de l’aide.

La configuration est générée dans le fichier /home/gerrit/etc/gerrit.config.

Un exemple de session :

*** Gerrit Code Review 2.13.7
*** 


*** Git Repositories
*** 

Location of Git repositories   [git]: /home/git

*** SQL Database
*** 

Database server type           [h2]: mysql

Gerrit Code Review is not shipped with MySQL Connector/J 5.1.21
**  This library is required for your configuration. **
Download and install it now [Y/n]? y
Downloading https://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.21/mysql-connector-java-5.1.21.jar ... OK
Checksum mysql-connector-java-5.1.21.jar OK
Server hostname                [localhost]: 
Server port                    [(mysql default)]: 
Database name                  [reviewdb]: gerrit
Database username              [gerrit]: 
gerrit's password              : 
              confirm password : 

*** Index
*** 


The index must be rebuilt before starting Gerrit:
  java -jar gerrit.war reindex -d site_path

*** User Authentication
*** 

Authentication method          [OPENID/?]: ?
       Supported options are:
         openid
         openid_sso
         http
         http_ldap
         client_ssl_cert_ldap
         ldap
         ldap_bind
         custom_extension
         development_become_any_account
         oauth
Authentication method          [OPENID/?]: http_ldap
Get username from custom HTTP header [y/N]? ?
Get username from custom HTTP header [y/N]? 
SSO logout URL                 :  
LDAP server                    [ldap://localhost]: 
LDAP username                  : gerrit
gerrit's password               : 
              confirm password : 
Account BaseDN                 : ou=ldapuser,dc=foo,dc=bar
Group BaseDN                   [ou=ldapuser,dc=foo,dc=bar]: 
Enable signed push support     [y/N]? 

*** Review Labels
*** 

Install Verified label         [y/N]? 

*** 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-7-openjdk-amd64/jre]: 
Copy gerrit-2.13.7.war to /home/gerrit/bin/gerrit.war [Y/n]? 
Copying gerrit-2.13.7.war to /home/gerrit/bin/gerrit.war

*** SSH Daemon
*** 

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

Gerrit Code Review is not shipped with Bouncy Castle Crypto SSL v152
  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 https://repo1.maven.org/maven2/org/bouncycastle/bcpkix-jdk15on/1.52/bcpkix-jdk15on-1.52.jar ... OK
Checksum bcpkix-jdk15on-1.52.jar OK

Gerrit Code Review is not shipped with Bouncy Castle Crypto Provider v152
** This library is required by Bouncy Castle Crypto SSL v152. **
Download and install it now [Y/n]? 
Downloading https://repo1.maven.org/maven2/org/bouncycastle/bcprov-jdk15on/1.52/bcprov-jdk15on-1.52.jar ... OK
Checksum bcprov-jdk15on-1.52.jar OK
Generating SSH host key ... rsa... dsa... done

*** HTTP Daemon
*** 

Behind reverse proxy           [y/N]? y
Proxy uses SSL (https://)      [y/N]? n
Subdirectory on proxy server   [/]: 
Listen on address              [*]: 127.0.0.1
Listen on port                 [8081]: 
Canonical URL                  [http://127.0.0.1/]: 

*** Cache
*** 


*** Plugins
*** 

Installing plugins.
Install plugin commit-message-length-validator version v2.13.7 [y/N]? y
Installed commit-message-length-validator v2.13.7
Install plugin download-commands version v2.13.7 [y/N]? y
Installed download-commands v2.13.7
Install plugin hooks version v2.13.7 [y/N]? y
Installed hooks v2.13.7
Install plugin replication version v2.13.7 [y/N]? 
Install plugin reviewnotes version v2.13.7 [y/N]? y
Installed reviewnotes v2.13.7
Install plugin singleusergroup version v2.13.7 [y/N]? y
Installed singleusergroup v2.13.7
Initializing plugins.
No plugins found with init steps.

Si vous obtenez le message d’erreur suivant :

Exception in thread "main" com.google.gwtorm.server.OrmException: Cannot initialize schema
[…]
Caused by: java.io.IOException: Cannot create repository All-Projects
[…]
Caused by: org.eclipse.jgit.errors.RepositoryNotFoundException: repository not found: Cannot create repository All-Projects
[…]
Caused by: java.io.IOException: Creating directories for /home/git/All-Projects.git failed

C’est que l’utilisateur gerrit n’a pas les droits de créer un dossier dans /home/git (ou le chemin renseigné).

Démarrage du démon

Avant tout chose, il faut construire l’index.

Note : L’utilisateur gerrit doit pouvoir accéder aux dépôts GIT dans /home/git.

$ java -jar bin/gerrit.war reindex

Puis lancer le démon :

$ bin/gerrit.sh start

Accéder au serveur web de Gerrit via http://localhost:8081 par exemple, et créer le premier administrateur.

Note : Si vous obtenez l’erreur Missing project All-Projects, il faudra peut-être supprimer la base gerrit et la recréer, puis relancer l'init.

Script d’init

Il faut copier le script gerrit.sh qui est compatible « script d’init ».

# install -m 700 -o root -g root /home/gerrit/bin/gerrit.sh /etc/init.d/gerrit

Puis créer /etc/default/gerritcodereview.

# echo "GERRIT_SITE=/home/gerrit" >> /etc/default/gerritcodereview

On pourra ensuite activer le script d’init, et faire les actions {start|stop|restart|check|status|run|supervise|threads}.

Configuration avancée

Reverse Proxy

Pour utiliser Apache devant Gerrit : https://gerrit-documentation.storage.googleapis.com/Documentation/2.13.7/config-reverseproxy.html

Exemple de VirtualHost :

<VirtualHost *:80>
  ServerName review.example.com

  CustomLog /var/log/apache2/gerrit.access.log combined
  ErrorLog  /var/log/apache2/gerrit.error.log

  ProxyRequests Off
  ProxyVia Off
  ProxyPreserveHost On

  <Proxy *>
    Require all granted
  </Proxy>

  AllowEncodedSlashes On
  ProxyPass / http://127.0.0.1:8081/ nocanon
</VirtualHost>

Note : Assurez-vous d’avoir activé le module apache proxy_http.

Il faudra s’assurer d’avoir dans la configuration de Gerrit :

[httpd]
    listenUrl = proxy-http://127.0.0.1:8081/

Authentification LDAP via Apache

Via Apache, on peut gérer l’authentification via LDAP (Il est donc nécessaire de mettre en place la section Reverse Proxy).

Il suffit d’ajouter dans le VirtualHost :

~~~{.apache] <Location “/login/”> AuthType Basic AuthName “Gerrit Code Review” Require valid-user AuthBasicProvider ldap AuthzLDAPAuthoritative on AuthLDAPURL “ldap://127.0.0.1:389/ou=people,dc=example,dc=com?uid?sub?(objectClass=*)” ~~~

Une fois passé cette authentification, Gerrit lui-même rapatrie les informations de l’utilisateur via LDAP (champ sn…) en se connectant avec l’utilisateur renseigné dans sa configuration (ou anonymous) ldap.username…

Monitoring

On peut surveiller avec Nagios la bonne réponse de l’interface web et la disponibilité du serveur SSH embarqué :

/usr/lib/nagios/plugins/check_http -H localhost -p 8081
/usr/lib/nagios/plugins/check_ssh -p 29418 localhost

Créer un utilisateur Gerrit via SSH

Avec un compte administrateur, vous devez d’abord uploader votre clé publique dans l’interface web.

Dans cet exemple, on crée le compte jenkins, on pousse sa clé publique et on le met dans le groupe « Non-Interactive Users ».

$ cat /home/gerrit/.ssh/jenkins.pub | ssh -p 29418 admin@localhost gerrit create-account --group "'Non-Interactive Users'" --ssh-key - jenkins

FAQ

Si vous obtenez l’erreur suivante :

[HTTP-56] WARN  com.google.gerrit.server.query.account.InternalAccountQuery : Ambiguous external ID gerrit:foo for accounts: 3, 1
[HTTP-56] ERROR com.google.gerrit.httpd.auth.container.HttpLoginServlet : Unable to authenticate user "foo"
com.google.gerrit.server.account.AccountException: Cannot assign external ID "gerrit:foo" to account 9; external ID already in use.
        at com.google.gerrit.server.account.AccountManager.create(AccountManager.java:268)
[…]

C’est peut-être un problème de cache. Essayez de le reconstruire avec :

$ bin/gerrit.sh stop
$ java -jar bin/gerrit.war reindex --index accounts
$ bin/gerrit.sh start