Tutoriel sur la mise en place d'un entrepôt distant GIT à partir de l'outil GITBlit

Régis POUILLER

Cet article présente Gitblit (serveur de dépôts Git) ainsi que son installation, son utilisation et son système de stockage des données.

Une discussion a été ouverte pour les commentaires sur la publication de cet article : [ Commentez ]

- Titre : Tutoriel sur la mise en place d'un entrepôt distant GIT à partir de l'outil GITBlit

- Auteur : Régis POUILLER

- Parution : 11 septembre 2013

- Licence : Copyright ® 2013 Régis POUILLER. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. INTRODUCTION

- I-A. Objectif

- I-B. Gestionnaires de versions

- I-C. Connaissances prérequises

- I-D. Versions des logiciels

- II. PRÉSENTATION

- II-A. Gitblit : serveur de dépôts Git

- II-B. Comparaison avec Github

- II-C. Versions de Gitblit

- II-D. Topologie de Gitblit

- III. INSTALLATION

- III-A. Installation de Gitblit

- III-B. Installation de Git

- III-C. Installation de Eclipse

- IV. UTILISATION

- IV-A. Création d'un utilisateur et d'une équipe

- IV-B. Création de dépôts

- IV-B-1. Exemple d'un dépôt visible par tout le monde

- IV-B-2. Exemple d'un dépôt visible uniquement par les utilisateurs avec droits

- IV-B-3. Système de droits de Gitblit

- IV-C. Utilisation du dépôt

- IV-C-1. Utilisation du dépôt depuis un client Git

- IV-C-2. Utilisation du dépôt depuis un client Eclipse avec EGit

- IV-C-2-a. Configuration de EGit

- IV-C-2-b. Clonage du dépôt

- IV-C-2-c. Push du projet

- IV-C-2-d. Import du projet

- V. DONNÉES DE GITBLIT

- V-A. Paramétrage de Gitblit

- V-B. Groupes de dépôts

- V-C. Utilisateurs

- V-D. Dépôts

- VI. POUR ALLER UN PEU PLUS LOIN

- VI-A. La fédération

- VI-B. La recherche avec Lucene

- VI-C. La personnalisation par hook Groovy

- VII. CONCLUSION

- VIII. REMERCIEMENTS

I - INTRODUCTION

I-A - Objectif

Git est un logiciel de gestion de versions décentralisé (voir I-B - Gestionnaires de versions) créé par Linus Torvalds.

Cet article n'a pas pour but de présenter Git. Pour cela, il y a déjà l'article Pro Git - Tout ce que vous devez savoir sur l'outil de contrôle distribué Git.

Cet article contient :

- la présentation de Gitblit ;

- son installation (ainsi que celle de Git et Eclipse) ;

- son utilisation (un exemple avec Git en client et un autre avec Eclipse et EGit en client) ;

- ses données (où les informations sont stockées) ;

- et pour finir un bref aperçu de quelques fonctionnalités plus « avancées » ou tout du moins d'une utilisation moins courante

La partie « utilisation » sera un exemple simple d'utilisation de Gitblit avec la création de deux dépôts : nous accéderons au premier grâce à git en client par la ligne de commande (ce qui permet de voir clairement les commandes utilisées), nous accéderons au deuxième grâce au plugin EGit de Eclipse (ce qui permet de voir un exemple d'utilisation plus intégré à un environnement de développement assez populaire).

Pour cela au préalable, nous installerons Gitblit, Git et Eclipse.

I-B - Gestionnaires de versions

Il existe trois types de gestionnaires de versions : local, centralisé et décentralisé.

Un gestionnaire de version local (exemple : RCS) permet de gérer les différentes versions de fichiers sur un poste en local. Ses avantages sont d'être rapide et de ne pas avoir de dépendances par rapport au fonctionnement d'une autre machine ou du réseau. Ses inconvénients sont de ne pas être adapté au travail en équipe et d'être sensible aux défaillances matérielles (nécessité d'établir un système de sauvegarde).

Un gestionnaire de version centralisé (exemple : CVS ou Subversion) permet de soumettre les différentes versions de fichiers sur un serveur central. Le serveur héberge les différentes versions des fichiers tandis que les postes clients récupèrent une version choisie et soumettent les modifications. Son avantage est d'être adapté au travail en équipe. Ses inconvénients sont d'être sensible aux défaillances matérielles du serveur (nécessité d'établir un système de sauvegarde), d'être un peu plus lent (communication réseau plutôt que local) et d'être dépendant du fonctionnement du serveur et du réseau.

Un gestionnaire de version décentralisé (exemple : Mercurial ou Git) permet de gérer les différentes versions de fichiers en local et de soumettre lorsqu'on le souhaite les modifications sur un serveur central. Le serveur héberge les différentes versions des fichiers. Les postes clients récupèrent l'intégralité des versions des fichiers. Les modifications sont validées en local puis poussées vers le serveur. Ses avantages sont d'être rapide (car une grande partie du travail s'effectue en local), adapté au travail en équipe, d'être moins sensible aux défaillances matérielles (bien qu'un système de sauvegarde reste une bonne pratique, elle est moins nécessaire, car chaque nœud peut permettre de retrouver l'intégralité des versions), de ne pas être dépendant du fonctionnement du serveur ou du réseau (accès seulement nécessaire lors du clonage et lors des échanges avec le reste de l'équipe). Un autre avantage (un peu plus subtil) est la possibilité de travailler indépendamment (fork, brouillon, tests…) tout en gardant les avantages de la gestion de versions (il est même possible de pousser ce nouveau travail avec toutes les anciennes et nouvelles versions vers n'importe quel dépôt). Ses inconvénients sont un temps un peu plus long lors du clonage d'un dépôt (l'intégralité des versions étant récupérées) et la difficulté de fusion de fichiers binaires si modifications simultanées (possible, car absence de verrou) sur deux postes clients.

Vous pouvez également lire cette page de l'article sur Git qui comporte notamment des diagrammes représentant les trois types de gestionnaires.

I-C - Connaissances prérequises

Pour une bonne compréhension de cet article, il est conseillé d'avoir des connaissances de base en gestion de versions, et plus particulièrement des notions du fonctionnement de Git.

I-D - Versions des logiciels

Pour la réalisation de cet article, les versions des outils (uniquement à titre indicatif pour les personnes souhaitant reproduire le déroulement de l'article) sont :

- Java Development Kit : 7 Update 25 ;

- Tomcat : 7.0.42

- Gitblit : 1.3.1 (versi ;on War) ;

- Git pour Windows : 1.8.3.4 ;

- Eclipse : Kepler (le plugin EGit est inclus depuis la version 4.1 de Eclipse).

II - PRÉSENTATION

II-A - Gitblit : serveur de dépôts Git

Gitblit est un serveur de dépôts Git. Le principal contributeur de ce projet est James Moger.

Gitblit est écrit en Java. C'est ce qui permet que Gitblit peut fonctionner à partir où le système comporte une machine virtuelle Java (y compris Windows et c'est un point intéressant, car Linux est mieux fourni en serveur Git que Windows). Gitblit repose sur JGit. JGit est une implémentation Java de Git. JGit est maintenu par la fondation Eclipse. JGit est également un composant d'autres produits écrits en Java : par exemple le plugin pour Git d'Eclipse (EGit), celui pour NetBeans (NBGit) et un logiciel de revue de code (Gerrit).

Gitblit permet d'avoir très simplement (le premier principe est d'ailleurs : Keep It Simple, Stupid) et très rapidement un serveur de dépôts Git. Gitblit est packagé avec toutes les dépendances nécessaires (il n'est pas nécessaire d'installer Git ou quoi que ce soit d'autre). Son troisième principe (en fait le deuxième est le même que le premier afin d'insister sur la simplicité) est que toutes les dépendances de Gitblit doivent être présentes sur un dépôt Maven public.

II-B - Comparaison avec Github

En comparaison au serveur de dépôts Github, Gitblit est très différent :

- Gitblit permet de centraliser les dépôts (comme pour un serveur CVS ou Subversion) pour des équipes de petite taille, tandis que Github supporte un nombre d'utilisateurs bien plus important.

- Gitblit permet d'avoir son propre serveur « en interne », tandis que Github est un service « en externe » (il héberge gratuitement les projets open source mais un dépôt privé est payant).

- Gitblit n'implémente que le protocole HTTP. Il est possible de lui ajouter le support du SSH avec Apache Mina. Mais ceci ne respecte pas le premier principe de Gitblit énoncé plus haut. Github propose les protocoles HTTPS et SSH (on peut également faire un checkout d'un dépot avec Subversion).

- Pour finir, avec Gitblit il est possible de travailler (cloner et pusher) sans aucune authentification.

II-C - Versions de Gitblit

Gitblit existe en quatre versions :

- GO (Windows) : la version standalone avec un serveur intégré pour Windows ;

- GO (Linux/OSX) : celle pour Linux et OSX ;

- Express : qui fonctionne avec RedHat's OpenShift cloud ;

- War : Webapp que l'on déploie dans un conteneur de servlet.

II-D - Topologie de Gitblit

Le schéma ci-dessous présente un exemple de topologie possible à partir de Gitblit.

Dans cet exemple, Gitblit est le serveur central. Les clients peuvent « cloner » les dépôts de Gitblit et éventuellement « pusher » des modifications dessus.

Le schéma ci-dessous présente un autre exemple de topologie possible à partir de Gitblit.

Un dépôt Git peut avoir plusieurs origines (dépôts distants liés). Ainsi dans cet exemple, nous avons un poste avec un client Git qui sert de passerelle entre deux serveurs de dépôts. D'un côté, nous avons notre serveur Gitblit et l'autre serveur de dépôt peut être un serveur public comme Github ou un autre serveur privé auquel on n'accède que ponctuellement. Dans cette utilisation, on peut voir Gitblit comme un serveur « proxy » qui permet d'échanger au sein d'une équipe tout en travaillant sur des sources provenant de l'« extérieur ».

Les deux exemples de topologie sont bien entendu combinables.

III - INSTALLATION

III-A - Installation de Gitblit

Nous allons installer la version War de Gitblit. J'ai une préférence pour cette version, car il y a un meilleur découpage des responsabilités : Gitblit a uniquement la responsabilité de serveur de dépôt tandis que le conteneur de servlet (ici Tomcat) assure la responsabilité de gestion des requêtes web.

Une fois le JDK et Tomcat installé, il suffit de renommer le fichier « gitblit-1.3.1.war » en « gitblit.war » et le déposer dans le dossier « webapps » de Tomcat.

Par défaut, les données de Gitblit (paramétrage et dépôts) sont stockées dans le dossier « WEB-INF\data » de l'application déployée soit dans ce cas d'installation de Tomcat dans « C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\gitblit\WEB-INF\data ». Il est conseillé de changer ce dossier par défaut ce qui rendra plus facile les mises à jour de Gitblit. Pour cela, il faut éditer le paramètre « baseFolder » (dans notre exemple, en le changeant en « D:\depotsGitblit ») dans le fichier « web.xml » de l'application et redémarrer l'application.

<context-param>
<param-name>baseFolder</param-name>
<param-value>D:\depotsGitblit</param-value>
</context-param>

Par ailleurs, Tomcat (depuis la version 6.0.10) bloque les caractères « / » dans les URL. Une des solutions est d'indiquer à Gitblit d'utiliser un autre caractère. Pour cela, il faut modifier le paramètre « web.forwardSlashCharacter » dans le fichier « gitblit.properties » contenu dans le dossier contenant les données de Gitblit comme ceci :

web.forwardSlashCharacter = !

Il est nécessaire de redémarrer Gitblit après la modification pour qu'elle soit prise en compte.

L'application est accessible à l'adresse http://localhost:8080/gitblit

III-B - Installation de Git

Lancer le programme « Git-1.8.3-preview20130601.exe » d'installation.

Cliquer sur le bouton « Next » à chaque fois sauf dans l'écran « Adjusting your PATH environment » où il faut choisir « Run Git from the Windows Command Prompt ».

III-C - Installation de Eclipse

Comme pour toutes les autres versions de Eclipse, simplement décompresser le zip.

IV - UTILISATION

Le compte et mot de passe de l'administrateur de Gitblit sont admin/admin. Une fois connecté en administrateur, il est possible d'accéder à la création d'utilisateurs ou de dépôts.

IV-A - Création d'un utilisateur et d'une équipe

Cliquer sur l'onglet « users ».

Cliquer sur le lien « new user ».

Une fois les informations saisies (si l'adresse mail correspond à un compte Gravatar, l'avatar Gravatar sera affiché pour cet utilisateur, pour les pushs par exemple), cliquer sur le bouton « save ».

Cliquer sur le lien « new team ».

Après avoir saisi le nom de l'équipe, sélectionner les membres de l'équipe.

Finaliser en cliquant sur le bouton « save ».

IV-B - Création de dépôts

Cliquer sur l'onglet « repositories ».

Sans entrer dans le détail du système de droits, nous allons créer deux dépôts : un visible de tout le monde, mais avec des droits en écriture uniquement pour les membres de l'équipe « rubriqueJava » et un autre visible uniquement du propriétaire.

IV-B-1 - Exemple d'un dépôt visible par tout le monde

Cliquer sur le lien « new repository ».

Saisir le nom du dépôt (le « / » permet de placer le dépôt dans un groupe de dépôts). Puis cliquer sur l'onglet « access permissions ».

Entrer le propriétaire et les droits (ici seuls les membres de l'équipe ont des droits en écriture, mais tout le monde voit le dépôt, même sans être authentifié). Puis cliquer que le bouton « save ».

IV-B-2 - Exemple d'un dépôt visible uniquement par les utilisateurs avec droits

Cliquer sur le lien « new repository ».

Saisir le nom du dépôt. Puis cliquer sur l'onglet « access permissions ».

Entrer le propriétaire et les droits (ici seul admin peut voir ce dépôt). Puis cliquer que le bouton « save ».

Ainsi l'utilisateur « rpouiller » ne voit pas le dépôt « private ».

IV-B-3 - Système de droits de Gitblit

Le système de droits de Gitblit (que nous avons vu dans l'onglet « access permissions » des dépôts) est très complet.

L'« access restriction » indique ce que l'on peut faire sans être authentifié :

- anonymous view, clone, & push : permet à un utilisateur non authentifié de tout faire ;

- authenticated push : permet à un utilisateur non authentifié de voir et de cloner le dépôt, pour écrire il est nécessaire d'être authentifié ;

- authenticated clone & push : permet à un utilisateur non authentifié de voir le dépôt, pour cloner et écrire il est nécessaire d'être authentifié ;

- authenticated view, clone, & push : seul un utilisateur authentifié peut faire quelque chose.

L'« authorization control » (inaccessible si l'on choisit l'« access restriction » anonymous view, clone, & push) indique le niveau de permission des utilisateurs authentifiés :

- grant RW+ permission to all authenticated users : tous les utilisateurs authentifiés ont automatiquement tous les droits sur ce dépôt ;

- grant fine-grained permissions to named users or teams : les droits des utilisateurs sont définis par les « user permissions » et les « team permissions ».

Les « user permissions » permettent de définir les droits de chaque utilisateur et les « team permissions » permettent de définir les droits au niveau des équipes. Ces options ne sont pas accessibles si l'on choisit l'« access restriction » anonymous view, clone, & push ou l'« authorization control » grant RW+ permission to all authenticated users. Les droits sont (du plus faible au plus important, un droit plus important incluant tous les droits plus faibles) :

- X (exclude) : pas de droits ;

- V (view) : droit de voir le dépôt ;

- R (clone) : droit de cloner le dépôt ;

- RW (push) : droit de pousser des commits sur le dépôt ;

- RWC (push, ref creation) : droit de créer une branche ;

- RWD (push, ref creation+deletion) : droit de supprimer une branche ;

- RW+ (push, ref creation+deletion+rewind) : droit complet incluant la suppression de modification.

Le système de droits de Gitblit s'applique au niveau d'un dépôt pour tous les dossiers et fichiers de ce dépôt.

IV-C - Utilisation du dépôt

IV-C-1 - Utilisation du dépôt depuis un client Git

En premier, nous allons accéder au dépôt « private » grâce à Git comme client.

Pour cloner le dépôt, il faut utiliser la commande suivante :

D:\dossierGit>git config --global user.name admin

D:\dossierGit>git config --global user.email admin@localhost

D:\dossierGit>git clone http://admin@localhost:8080/gitblit/git/private.git
Cloning into 'private'...
Password for 'http://admin@localhost:8080':
warning: You appear to have cloned an empty repository.

D:\dossierGit>

Créer un fichier texte dans le dossier « D:\dossierGit\private ».

Puis passer les commandes suivantes :

D:\dossierGit>cd private

D:\dossierGit\private>git add article.txt

D:\dossierGit\private>git commit
[master (root-commit) f5031c9] Premier commit
1 file changed, 1 insertion(+)
create mode 100644 article.txt

D:\dossierGit\private>git push origin master
Password for 'http://admin@localhost:8080':
Counting objects: 3, done.
Writing objects: 100% (3/3), 242 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
remote: Updating references: 100% (1/1)
To http://admin@localhost:8080/gitblit/git/private.git
* [new branch]      master -> master

D:\dossierGit\private>

Pour voir le fichier sur le serveur, cliquer sur le dépôt concerné.

Pour cliquer sur le lien « tree » du commit.

Pour cliquer sur le lien « view ».

IV-C-2 - Utilisation du dépôt depuis un client Eclipse avec EGit

Maintenant, nous allons accéder au dépôt « Java » grâce à Eclipse et EGit comme client.

IV-C-2-a - Configuration de EGit

Configurer le nom et l'e‑mail dans les préférences de EGit.

IV-C-2-b - Clonage du dépôt

Cliquer sur l'icône permettant d'ouvrir d'autres perspectives.

Choisir la perspective « Git Repository Exploring ».

Cliquer sur « Clone a Git repository ».

Entrer les informations du dépôt distant. Puis cliquer sur « Next ».

Cliquer sur « Next ».

Cliquer sur « Finish ».

Le dépôt a été cloné en local.

IV-C-2-c - Push du projet

Créer un projet Java simple.

Faire un clic droit sur le nom du projet. Puis, choisir « Team > Share Project… ».

Choisir le type de repository « Git ». Puis, cliquer sur « Next ».

Choisir le dépôt local. Puis, cliquer sur « Finish ».

Faire un clic droit sur le projet. Puis choisir « Team > Commit… ».

Entrer les informations et cocher les fichiers qui doivent être commités. Puis cliquer sur « Commit and push… ».

Entrer le compte et le mot de passe. Puis cliquer sur « OK ».

Cliquer sur « OK ».

On retrouve le push sur le serveur Gitblit.

IV-C-2-d - Import du projet

Pour importer un projet présent dans le dépôt local suite au clonage d'un dépôt distant. Faire un clic droit dans « Package Explorer ». Puis cliquer « Import… ».

Sélectionner « Projects from Git ». Puis cliquer sur « Next ».

Sélectionner « Local ». Puis cliquer sur « Next ».

Sélectionner le dépôt local. Puis cliquer sur « Next ».

Sélectionner le dossier du projet dans le dépôt. Puis cliquer sur « Finish ».

Le projet a été importé. Il est maintenant de faire des modifications que l'on poussera sur le dépôt distant et de récupérer les modifications que d'autres auront poussées sur le dépôt distant.

V - DONNÉES DE GITBLIT

Comme vu lors de l'installation, les données de Gitblit (paramétrage et dépôts) sont stockées par défaut dans le dossier « WEB-INF\data » de l'application déployée soit dans ce cas d'installation de Tomcat dans « C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\gitblit\WEB-INF\data ». Il est cependant conseillé de changer ce dossier comme vu dans le paragraphe installation.

V-A - Paramétrage de Gitblit

Comme vu également lors de l'installation, le fichier « gitblit.properties » contient le paramétrage de Gitblit.

Il est possible d'avoir un aperçu de ce fichier sur le site de Gitblit.

V-B - Groupes de dépôts

Le fichier « projects.conf » contient la liste des groupes de dépôts. Par défaut, il contient ceci :

[project "main"]
title = Main Repositories
description = main group of repositories

Si on le modifie comme ceci :

[project "main"]
title = Main Repositories
description = main group of repositories
[project "developpez"]
title = Dépôts de developpez
description = Contient les dépôts pour le site developpez.com

On obtient le changement suivant :

V-C - Utilisateurs

Le fichier « users.conf » contient la liste des utilisateurs. Actuellement, il contient ceci :

[user "admin"]
password = admin
cookie = dd94709528bb1c83d08f3088d4043f4742891f4f
role = "#admin"
role = "#notfederated"
[user "rpouiller"]
password = MD5:9ea2bf8fd4605afd5063b124759bba01
cookie = 81bde4cd41269a45a1b4e51b4fccb23d26a0d945
displayName = Régis POUILLER
emailAddress = pouiller.gitblit@gmail.com
role = "#none"
repository = RW+:developpez/java.git
repository = X:private.git
[team "rubriqueJava"]
role = "#none"
repository = RW+:developpez/java.git
user = rpouiller

On peut rajouter un utilisateur avec tous les droits sur le dépôt « private » comme ceci :

[user "admin"]
password = admin
cookie = dd94709528bb1c83d08f3088d4043f4742891f4f
role = "#admin"
role = "#notfederated"
[user "rpouiller"]
password = MD5:9ea2bf8fd4605afd5063b124759bba01
cookie = 81bde4cd41269a45a1b4e51b4fccb23d26a0d945
displayName = Régis POUILLER
emailAddress = pouiller.gitblit@gmail.com
role = "#none"
repository = RW+:developpez/java.git
repository = X:private.git
[team "rubriqueJava"]
role = "#none"
repository = RW+:developpez/java.git
user = rpouiller
[user "test"]
password = test
role = "#none"
repository = RW+:private.git

On obtient ceci :

V-D - Dépôts

Les dépôts sont contenus dans le sous-dossier « git ». Dans notre cas, on retrouve d'ailleurs dans le sous-dossier « git » :

- le sous-dossier « developpez » qui correspond au groupe de dépôts et qui contient lui-même le sous-dossier « java.git » correspondant au dépôt « java » ;

- et le sous-dossier « private.git » qui correspond au dépôt « private ».

VI - POUR ALLER UN PEU PLUS LOIN

Voici quelques fonctionnalités de Gitblit qui n'ont pas été abordées dans cet article, mais qui peuvent tout de même être intéressantes.

VI-A - La fédération

Cette fonctionnalité permet de cloner dans une instance de Gitblit les dépôts d'une ou plusieurs autres instances de Gitblit. Le mécanisme se charge de maintenir la synchronisation à jour. Cela peut permettre d'avoir facilement une copie d'un ensemble de dépôts.

Pour toutes informations complémentaires, voir la page du site.

VI-B - La recherche avec Lucene

L'activation de l'indexation des dépôts grâce au moteur de recherche Lucene permet des commit plus rapides et des recherches rapides et plus complexes.

Pour toutes informations complémentaires, voir la page du site.

VI-C - La personnalisation par hook Groovy

Il est possible d'utiliser des scripts hook (écrits par l'utilisateur ou parmi ceux fournis avec Gitblit) pour effectuer des opérations lors de la réception et du traitement d'événement de « push » d'un client sur le serveur.

Pour toutes informations complémentaires, voir la page du site.

VII - CONCLUSION

Nous avons pu voir que Gitblit est une solution très intéressante pour héberger « en interne » un dépôt central pour une équipe. Il est très simple à mettre en place et peut répondre à l'ensemble des besoins les plus courants.

VIII - REMERCIEMENTS

Je remercie très sincèrement :

- www.developpez.com qui me permet de publier cet article ;

- Nono40 et djibril pour leurs outils ;

- Mickael Baron pour sa relecture technique et ses conseils qui m'ont fait pas mal remanier cet article, mais ont permis de livrer un résultat plus abouti ; ;-)

- ClaudeLELOUP pour sa relecture orthographique rigoureuse.