13. Gerrit¶

Avertissement

La traduction de cette page est incomplète et non maintenue. Veuillez vous rendre sur http://doc-en.tuleap.net/en/latest/user-guide/gerrit.html

L’intégration avec Gerrit est encore récente; une bonne connaissance de Gerrit et de Tuleap sont donc requis.

Gerrit est un outil de review de code qui se base sur git. Il a aussi la capacité de gérer les permissions d’accès aux dépôts.

Plus d’informations sur Gerrit : http://code.google.com/p/gerrit/

13.1. Feature overview¶

L’intégration de Gerrit avec Tuleap a été faite aussi légèrement que possible afin de donner la possibilité aux utilisateurs s’utiliser Gerrit a son plein potentiel. Tuleap simplifie la création et la gestion des dépôts, des utilisateurs et des groupes d’utilisateurs. Tuleap ne limite en rien les capacités de Gerrit.

On peut connecter plusieurs serveurs Gerrit à une même instance de Tuleap et vice-versa. Un serveur Gerrit peut aussi être utilisé seul, sans Tuleap, en toute autonomie pour gérer les projets et utilisateurs.

13.2. Migration d’un dépôt git vers Gerrit¶

En tant qu’administrateur d’un projet, on peut migrer un dépôt git vers Gerrit.

Après la migration, tous les fichiers du dépôt migré seront répliqués sur le serveur Gerrit avec des permissions par défaut générés à partir des permissions sur Tuleap.

Du coté Tuleap, dès que le dépôt est migré, la version Tuleap n’as plus que les droits de lecture ; la référence étant sur Gerrit.

Les utilisateurs peuvent continuer à visualiser le dépôt et son contenu, en faire un forks ou un clone ; toutes les opérations d’écriture sont suspendues (même pour les admins).

En revanche, toutes les changements effectués sur le dépôt git migré sur Gerrit sont répliqués sur Tuleap. Quand un développeur fait un commit sur Gerrit, quelques secondes plus tard, ce même commit est répliqué sur le dépôt Tuleap.

Un effet secondaire de la migration est que tous les groupes d’utilisateurs d’un projet sont répliqués sur Gerrit. Voir ci-dessous.

13.2.1. Création de projet¶

Dans la terminologie Gerrit, un dépôt git s’appelle un “project”. Afin d’eviter toute confusion, nous l’appellerons un “Gerrit project”.

In following sections, we will take the example of an imaginary Tuleap project “mozilla” with two git repositories “thunderbird” and “firefox”.

Project admins migrate to Gerrit “firefox” git repository. After a couple of minutes, on Gerrit side there is:

One top level Gerrit project “mozilla”
One sub project “mozilla/firefox” created

The Gerrit project “mozilla/firefox” contains sources and is where developer will push for review.

The Gerrit project “mozilla” is a permission only project (no sources can be pushed into) and is meant to group all git repositories that come from the same Tuleap project. It’s convenient to define common permissions for several repositories.

13.2.2. Permissions¶

Tuleap comes with a default set of permissions for each Gerrit project. Those permissions are set at project migration only. No subsequent modifications of permissions are done by Tuleap.

Default Gerrit access rights are based permissions set on corresponding Tuleap git repository at migration. For details on on gerrit access rights please have a look to http://gerrit-documentation.googlecode.com/svn/Documentation/2.5.2/access-control.html

Read:
- On ‘heads’
  - Read
  - label code-review -1..+1
- On ‘for/refs/heads’
  - Push
- On ‘tags’
  - Read
Write:
- On ‘heads’
  - Read
  - Create
  - forgeAuthor
  - label code-Review -2..+2
  - label verified -1..+1
  - submit
  - push
  - pushMerge
- On ‘for/refs/heads’
  - Push
  - PushMerge
- On tags
  - Read
  - pushTags
Rewind:
- On ‘heads’
  - Push +force

As project administrator, you can redefine the whole Gerrit permission scheme as you wish. If you need to create new user groups to tailor your workflow, see “User groups management” section below.

13.3. User groups management¶

User group management helps to keep consistent your teams between Tuleap and Gerrit. When someone join or leave your team, just add or remove it in Tuleap project and it’s automatically propagated to Gerrit.

The user group management follow the same naming pattern than projects. Given I have a “mozilla” Tuleap project with one special user group “Developers”, I will get on Gerrit server:

mozilla/project_members
mozilla/project_admins
mozilla/Developers

The two first user groups are created by default out of “Members” and “Admins” list.

As soon as one git repository was migrated to Gerrit. All modifications done to Tuleap project membership is replicated:

When I create a new Tuleap user group, a new Gerrit user group is created
When I add users as members of a user group on Tuleap, they became members of the corresponding user group on Gerrit
When I remove members on Tuleap, they are removed from corresponding Gerrit group
When I create a binding between two user groups in Tuleap, the two groups are linked in gerrit (even if the user group, source of the binding doesn’t exist on Gerrit yet).
When I remove a binding between two user groups in Tuleap, the source group is no longer included in the target group and all members of the source group are added into the target group.

13.4. Manage user SSH keys¶

To help people to start working with Gerrit, user ssh keys stored in Tuleap can be imported on Gerrit server.

As soon as a user belongs to a Tuleap project with at least one git repository migrated to Gerrit, all modifications done to user ssh keyring are propagated to the corresponding user account on the server. In other words, when user add an ssh key on Tuleap, the ssh key is added on Gerrit server and vice et versa.

This key management doesn’t override Gerrit ssh keys, it will not delete keys Tuleap doesn’t manage.

Note: the first connexion between Tuleap user account and Gerrit user account is not done automatically. Each user have to go on Tuleap “Account Maintenance” page and click “Push SSH keys” button. All future operations are automated.

13.5. Setup¶

Integration only works with 2.5.x version of gerrit.

Prerequisites:

LDAP plugin must be installed, configured and active. Both Tuleap and Gerrit rely on LDAP for common user management.

From now on, you will need:

What	Value
a tuleap instance	my.tuleap.server.net
a gerrit instance	gerrit.instance.com
your local workstation	workstation
the gerrit general administrator	admin-my.tuleap.server.net (must be a valid LDAP user)
the gerrit super administrator	gerrit-adm (must be a valid LDAP user)

13.5.1. Install and configure Gerrit server¶

Follow the steps here up until and including the section Initialize the Site

13.5.1.1. Configure LDAP integration¶

To connect as gerrit-adm, you first need to configure gerrit to authenticate with LDAP.

Edit etc/gerrit.config to use LDAP auth. Example:

[auth]
    type = LDAP
[ldap]
    server = ldap://myldap.server.com
    accountBase = ou=People,dc=cro,dc=enalean,dc=com
    groupBase = ou=Group,dc=cro,dc=enalean,dc=com
    accountFullName = cn

Restart or stop/start your gerrit as explained in the gerrit quick_install documentation.

13.5.1.2. Create the gerrit administrator account¶

Start the gerrit instance, go to the web ui and create the administrator account (the first account registered is the administrator) for gerrit-adm.

Through the gerrit web ui, go to the settings and upload your very own local ssh key.

# copy the output of this and paste it in gerrit
you@workstation$ cat $HOME/.ssh/id_rsa.pub

This gives you ultimate rights over gerrit.instance.com as a super administrator. It’s bad practice to use this account for anything but major changes so we will add a general administrator account for taking care of the day to day administration of gerrit.instance.com.

13.5.1.3. Configure gerrit replication¶

To configure gerrit replication we need to use the gerrit replication plugin. This plugin comes as part of the gerrit package gerrit-full-2.5.1.war that you have downloaded. There are two steps to using this package. Let’s assume you have already followed the steps in the link above and have a folder called _gerrit_testsite_ where all the gerrit files are located.

First login as admin-my.tuleap.server.net on gerrit.instance.com and create the group my.tuleap.server.net-replication. Do not add any users to it. Make group visible to all registered users:
- Go to Groups > Create New Group
- Create my.tuleap.server.net-replication
- Then go to Groups > List > my.tuleap.server.net-replication > General
- Tick the Group option Make group visible to all registered users
- and save
Now go back to the gerrit package you downloaded. You inflate the jar of the replication plugin into gerrit_testsite/plugins/.
```
gerrit@gerrit.instance.com$ unzip -j gerrit-full-2.5.2.war WEB-INF/plugins/replication.jar -d gerrit_testsite/plugins/
```
Finally, you need to configure the plugin. Go to gerrit_testsite/etc/ and create a file called replication.config:
```
gerrit@gerrit.instance.com$ cd gerrit_testsite/etc
gerrit@gerrit.instance.com$ touch replication.config
```

In this file put the following contents

[remote "my.tuleap.server.net"]
  url = gitolite@my.tuleap.server.net:${name}.git
  push = +refs/heads/*:refs/heads/*
  push = +refs/tags/*:refs/tags/*
  authGroup = my.tuleap.server.net-replication

13.5.2. Connect Gerrit and Tuleap servers¶

13.5.2.1. Setup administrator account for Tuleap¶

As codendiadm on Tuleap server generate a new SSH key for gerrit:

codendiadm@my.tuleap.server.net$ ssh-keygen -P "" -f /home/codendiadm/.ssh/id_rsa-gerrit

On Gerrit server log-in with the LDAP credentials for admin-my.tuleap.server.net and give it the SSH public key you just created (/home/codendiadm/.ssh/id_rsa-gerrit.pub)
On Gerrit server, log back in as gerrit-adm and give admin-my.tuleap.server.net Administrator rights: In the interface, go to Groups > List > Administrators then add admin-my.tuleap.server.net in the input box and click on Add.

13.5.2.2. Grant write accesses to administrators¶

On Gerrit server, as Administrator, go to Projects > List > All-projects > Access.

Look for the reference refs/meta/config
- Add Read permission to Groups Administrators
Add a new reference refs/meta/*
- Grant Read and Push permission to Administrators This is necessary to allow Tuleap to update the project.config of any project
Look for the reference /refs/*
- Add Forge Committer Identity permission for the group Administrators (this will allow Tuleap to push commits it’s not the direct author of).

13.5.2.3. Configure the email of the administrator¶

First, shell into the box on which Tuleap is running as either codendiadm. From there, you will need to run this:

codendiadm@my.tuleap.server.net$ ssh -i /home/codendiadm/.ssh/id_rsa-gerrit admin-my.tuleap.server.net@gerrit.instance.com -p 29418 gerrit gsql
UPDATE account_external_ids SET email_address = 'codendiadm@my.tuleap.server.net' WHERE external_id LIKE '%:admin-my.tuleap.server.net';
UPDATE accounts SET preferred_email = 'codendiadm@my.tuleap.server.net' WHERE full_name = 'admin-my.tuleap.server.net';
exit;
codendiadm@my.tuleap.server.net$ ssh -i /home/codendiadm/.ssh/id_rsa-gerrit admin-my.tuleap.server.net@gerrit.instance.com -p 29418 gerrit flush-caches

Note: This step cannot be done through the web ui since the email is hard coded to codendiadm@my.tuleap.server.net which by default has no mbox and a confirmation email is sent to this address.

13.5.3. Integrating Tuleap and Gerrit¶

Shell into the box on which your Gerrit instance is running and grab the output of the default public key that will be used for the replication:
```
gerrit@gerrit.instance.com$ cat ~/.ssh/id_rsa.pub
```

If it doesn’t exist then you need to create it via ssh-keygen as above.

As site admin on Tuleap, go to Admin > plugins > git plugin and add a gerrit server:

Key	Value
Host	`gerrit.instance.com`
Port	`29418`
Login	`admin-my.tuleap.server.net`
Identity File	`/home/codendiadm/.ssh/id_rsa-gerrit`
Replication SSH Key	copy and paste the output of the public key

Finally, it is important for the codendiadm user on my.tuleap.server.net to have gerrit.instance.com as part of its known hosts and vice versa. To ensure this:

# root on Tuleap
root@my.tuleap.server.net$ ssh -p 29418 -i /home/codendiadm/.ssh/id_rsa-gerrit admin-my.tuleap.server.net@gerrit.instance.com gerrit -h

# codendiadm on Tuleap
codendiadm@my.tuleap.server.net$ ssh -p 29418 -i /home/codendiadm/.ssh/id_rsa-gerrit admin-my.tuleap.server.net@gerrit.instance.com gerrit -h

# Gerrit user on Gerrt server (replication)
gerrit@gerrit.instance.com$ ssh gitolite@my.tuleap.server.net

13.5.3.1. Activation de la suppression d’un Gerrit project via Tuleap¶

[Ce plugin est originaire de https://gerrit.googlesource.com/plugins/delete-project]

Depuis Tuleap 6.5, il est possible de supprimer un Gerrit project après que celui-ci ait été déconnecté de Tuleap. Pour que cette fonctionnalité soit proposée il faut installer un plugin supplémentaire.

Télécharger le plugin https://tuleap.net/file/download.php/101/65/p5_r58/deleteproject.jar
Pour installer le plugin, vous avez deux options.
- option 1 – Copier le plugin dans le dossier de ‘plugins’ sur votre instance Gerrit instance puis exécuter
```
ssh -p29418 admin-my.tuleap.server.net@gerrit.instance.com gerrit plugin enable deleteproject
```
- option 2 – Mettre le plugin quelquepart d’accessible puis exécuter
```
ssh -p29418 admin-my.tuleap.server.net@gerrit.instance.com gerrit plugin install <url du plugin>
```

13. Gerrit¶

13.1. Feature overview¶

13.2. Migration d’un dépôt git vers Gerrit¶

13.2.1. Création de projet¶

13.2.2. Permissions¶

13.3. User groups management¶

13.4. Manage user SSH keys¶

13.5. Setup¶

13.5.1. Install and configure Gerrit server¶

13.5.1.1. Configure LDAP integration¶

13.5.1.2. Create the gerrit administrator account¶

13.5.1.3. Configure gerrit replication¶

13.5.2. Connect Gerrit and Tuleap servers¶

13.5.2.1. Setup administrator account for Tuleap¶

13.5.2.2. Grant write accesses to administrators¶

13.5.2.3. Configure the email of the administrator¶

13.5.3. Integrating Tuleap and Gerrit¶

13.5.3.1. Activation de la suppression d’un Gerrit project via Tuleap¶

Table des Matières

Sujet précédent

Sujet suivant

Cette page

Navigation

13. Gerrit¶

13.1. Feature overview¶

13.2. Migration d’un dépôt git vers Gerrit¶

13.2.1. Création de projet¶

13.2.2. Permissions¶

13.3. User groups management¶

13.4. Manage user SSH keys¶

13.5. Setup¶

13.5.1. Install and configure Gerrit server¶

13.5.1.1. Configure LDAP integration¶

13.5.1.2. Create the gerrit administrator account¶

13.5.1.3. Configure gerrit replication¶

13.5.2. Connect Gerrit and Tuleap servers¶

13.5.2.1. Setup administrator account for Tuleap¶

13.5.2.2. Grant write accesses to administrators¶

13.5.2.3. Configure the email of the administrator¶

13.5.3. Integrating Tuleap and Gerrit¶

13.5.3.1. Activation de la suppression d’un Gerrit project via Tuleap¶

Table des Matières

Sujet précédent

Sujet suivant

Cette page

Recherche rapide

Navigation