Héberger des dépôts git avec gitolite

lun. 02 sept. 2013 by Marmotte

Gitolite est un outil qui permet de faciliter l'hébergement de dépôts git. Il se charge, par défaut, uniquement de la gestion des droits d'accès aux différents dépôts, mais peut aussi effectuer d'autres tâches, comme la configuration automatique des dépôts hébergés.

Installation¶

Sous Debian, il suffit d'installer le paquet gitolite.

$ sudo apt-get install --no-install-recommends gitolite

Configuration de base¶

Pour son fonctionnement, gitolite repose sur un dépôt git, dans lequel on trouve les clés SSH des utilisateurs autorisés et les fichiers de configuration. Lorsqu'un administrateur pousse une modification sur ce dépôt, la liste des utilisateurs autorisés et la configuration sont automatiquement mises à jour.

Le paquet fourni par Debian sait générer lui même ce dépôt. Pour cela, il faut lancer la configuration automatique.

$ sudo dpkg-reconfigure gitolite

Le script de configuration demande la clé SSH publique de l'administrateur. Il est possible de coller le contenu du fichier, ou donner son chemin, s'il est présent sur le serveur. Dans le second cas, le fichier est simplement copié, il conserve donc le même nom.

Ce dépôt git est initialisé avec la clé SSH fournie, et un fichier de configuration de base. Il est nommé gitolite-admin, et est situé à la racine. Pour configurer gitolite, il faut commencer par récupérer le dépôt de configuration.

$ git clone ssh://gitolite@<hostname>/gitolite-admin

Configuration¶

Clés SSH des utilisateurs¶

Les fichiers contenant les clés SSH des utilisateurs doivent comporter l'extension .pub, et être placés dans le répertoire keydir.

Il n'est possible de mettre qu'une seule clé SSH par fichier. Il est par contre possible de donner plusieurs clés SSH pour un même utilisateur, dans plusieurs fichiers, en les nommant <username>@<hostname>.pub plutôt que simplement <username>.pub.

Gitolite n'utilise alors que la première partie du nom de fichier comme identifiant dans son fichier de configuration, la seconde partie servant uniquement à différencier les fichiers. Cette méthode permet de ne pas avoir à modifier le fichier de configuration pour ajouter une second clé à un même utilisateur.

Fichiers de configuration¶

Les fichiers de configuration peuvent contenir des blocs de trois formats différents.

Inclusion d'un autre fichier de configuration
```
include "<FilePath>.conf"
```
Note : Le chemin peut être une espression régulière, par exemple projects/*.conf.
Définition de groupes
```
@<GroupName> = <Element> [<Element> ...]
```
Note : Les éléments peuvent être eux-mêmes des groupes.
Définition de droits d'accès aux dépôts
```
repo <RepositoryPath> [<RepositoryPath> ...]
    <Access> [<BranchRegex>] = <Username> [<Username> ...]
```
Note : Les <RepositoryPath> et <UserName> peuvent être directement le nom des éléments, ou des noms de groupes.

Différents droits d'accès¶

Gitolite définit quatre droits d'accès différents :

- = Interdiction
R = Accès en lecture seule
RW = Accès en lecture et écriture
RW+ = Accès en lecture et écriture, avec le droit de supprimer des données (commits, branches, etc.)

Groupes¶

Pour simplifier la lecture et la maintenance du fichier de configuration, il est possible de définir des groupes. Un groupe est simplement un élément qui regroupes d'autres éléments.

La définition des groupes d'utilisateurs et des groupes de dépôts n'est pas différenciée. Seul l'emplacement où ils sont utilisés les différencie.

Il est alors possible de définir ces groupes :

@admins = admin1 admin2
@team1 = user1 user2
@team2 = user1 user3
@users = @admins @team1 @team2 user4

@projects_team1 = project/first project/second
@projects_team2 = project/first project/third

Note : losqu'on définit plusieurs fois un même nom de groupe, il n'est pas écrasé. Les nouveaux éléments sont juste ajoutés dans le groupe.

Note : Le groupe @all est un nom réservé qui signifie tous les utilisateurs ou tous les dépôts selon l'endroit où il est utilisé.

Pour les utiliser, il suffit de mettre les noms de groupes, comme n'importe quel autre nom d'élément dans la configuration. Par exemple, les groupes créés précédemment peuveut être utilisés comme ça :

repo @projects_team1 project/secret
    R                   = user4
    RW                  = @team1
    RW+                 = @admins

repo @projects_team2
    R                   = @users
    RW                  = @team2 user4
    RW+                 = @admins

Gestion fine des accès¶

Les règles d'accès sont vérifiées dans l'ordre d'apparition. Il est donc possible de les cumuler pour gérer finement les droits.

Par exemple, si on veut donner les droits de lecture et écriture sur toutes les branches à l'utilisateur marmotte, sans lui laisser le droit de modifier la branche master, nous mettrons :

repo <RepositoryPath>
    R   master          = marmotte
    -   master          = marmotte
    RW                  = marmotte

Configuration avancée¶

Le fichier de configuration de gitolite se nomme .gitolite.rc et se situe à la racine du répertoire de l'utilisateur gitolite, qui est par défaut /var/lib/gitolite/.

Ce fichier contient des variables permettant d'autoriser certaines syntaxes de configuration avancées dans les fichiers du dépôt de configuration.

Définition des dépôts par des expression régulières¶

Il est possible de définir les noms des dépôts par des expressions régulières en donnant la valeur 1 à la variable $GL_WILDREPOS. Dans ce cas, les instructions du bloc seront appliquées à tous les dépôts correspondant à l'expression donnée.

Autoriser les utilisateurs à créer des dépôts¶

Lorsque la variable $GL_WILDREPOS est activée, les utilisateurs peuvent être autorisés à créer des dépôts. Le droit de création de dépôts est C.

repo public/CREATOR/.*
    C                   = <Username>
    RW+                 = CREATOR
    RW                  = @users

repo project/.*
    C                   = @maindevs
    RW                  = @devs

Note : Le nom CREATOR utilisé ici est un nom réservé, remplacé automatiquement par le nom de l'utilisateur qui crée le dépôt.

Configuration des dépôts¶

Il est possible de définir des valeurs pour la configuration des dépôts directement depuis le dépôt de configuration de gitolite.

La variable du fichier de configuration est nommée $GL_GITCONFIG_KEYS, ou $GIT_CONFIG_KEYS, selon la version de gitolite. Elle contient une liste d'expressions régulières, séparées par des espaces, définissant les variable de configuration de git qu'il est autorisé de modifier depuis le dépôt de configuration. Par exemple : "", ".*" ou "hooks.* user.name user.email".

Une fois cette variable configurée, la définition des valeurs se fait avec le mot-clé config.

repo @all
    config hooks.mailinglist = commits@example.com

Note : Il est possible d'insérer dynamiquement le nom du dépôt en utilisant la variable %GL_REPO.
repo project/.*
    config hooks.emailprefix = "[%GL_REPO] "