====== Dépôts git ======

===== Qu'est-ce que « Git » ? =====

Git est un programme informatique permettant de garder un historique de différentes versions d'un fichier ou d'un dossier.

Avec Git, vous pouvez donc remonter dans le temps et retrouver un document dans un état précédent.

Git est un programme que vous installez sur votre machine. Il est possible de synchroniser votre copie locale de vos fichiers / dossiers avec un serveur distant.

Quand vous versionnez un dossier, celui-ci devient un "dépôt git". Pour parler d'un dépôt hébergé sur un serveur on parle alors de "dépôt distant".

Plusieurs utilisateurs peuvent utiliser le même serveur Git. Il est possible de travailler en même temps que quelqu'un d'autre sur un même projet.

Chaque utilisateur d'un dépôt Git dispose d'une copie locale du projet : ainsi, si le serveur tombe, les différents utilisateurs peuvent reconstruire le dépôt distant avec les dernières sauvegardes ("commits") dont ils disposent.

La communication entre un dépôt Git distant et votre machine peut passer par différents protocoles. Le plus commun est SSH. C'est pour cela qu'il vous faut avoir une paire de clés SSH pour récupérer un dépôt (on parle alors de "cloner" un dépôt), mettre à jour un dépôt (on parle de "push") ou encore pour récupérer la dernière mise à jour (on parle de "pull").

===== L'intérêt de s'en servir =====

Ça permet de travailler facilement à plusieurs sur des documents et/ou du code.

Plus spécifiquement :

  * documents de l'asso (règlement intérieur, etc)
  * compte-rendus de réunion
  * travail graphique (même si c'est pas super de faire du //versioning// sur des fichiers binaires)
  * développement d'outils pour l'asso (site, SI, etc)


===== Liste des dépôts =====

Les dépôts sont gérés par [[gitlab|Gitlab]].

Voici les principaux dépôts utilisés par l'association :

^ Nom du dépôt      ^ Description                                            ^ Conditions d'accès ^
|[[https://git.faimaison.net/faimaison-membres/membres|membres]]            | Dépôt dédié aux membres et aux documents sur la vie de l'association : Comptes-rendus de réunion, d'assemblée générale, etc.| Accès réservé aux membres                                    |
|[[https://git.faimaison.net/faimaison-public/graphisme|graphisme]]          | Dépôt dédié aux documents graphiques : logos, flyer, templates, etc.| Accès libre|
|[[https://git.faimaison.net/faimaison-public/sdtan|sdtan]]              | Dépôt dédié au projet sur le SDTAN (schémas directeurs territoriaux d'aménagement numérique)| Accès libre|
|[[https://git.faimaison.net/faimaison-adminsys/adminsys|adminsys]]           | Dépôt dédié au groupe de travail adminsys              | Accès réservé |
|[[https://git.faimaison.net/faimaison-membres/site-pelican|site-pelican]]       | Dépôt dédié à notre site Internet  - Techno : Pelican  | Accès libre|
|[[https://code.ffdn.org/FFDN/coin|si]]                 | Dépôt dédié à notre SI : Coin - Techno : Django        | Accès réservé|
|[[https://git.faimaison.net/faimaison-bureau/bureau|bureau]] | Dépôt contenant des documents administratifs et comptables. | Accès réservé au bureau |
|[[https://git.faimaison.net/cafe-vie-privee/cafe-vie-privee|café vie privée]] | Dépôt dédié au collectif Café vie privée : doc d'atelier, de sensibilisation, communication. | Accès libre |

Par ailleurs les groupes Gitlab suivants sont définis :

^ Nom du dépôt        ^ Description                            ^ Conditions d'accès                                            ^
|faimaison-adminsys   | projets utilisés par les adminsys      | lecture = membres ; contribution = adminsys                   |
|faimaison-bureau     | projets utilisés par le bureau         | lecture = membres du bureau ; contribution = membres du bureau|
|faimaison-membres    | projets utilisés par les membres       | lecture = membres de faimaison ; contribution = membres de faimaison |
|faimaison-public     | projets publics                        | lecture = tout le monde ; contribution = membres de faimaison |

Pour contribuer il vous faut un accès.

===== Comment accéder aux dépôts de FAImaison ? =====

Rendez-vous sur la page dédiée à [[gitlab|Gitlab]]

===== Serveurs git =====

Voir page [[backup#depot git|backups]].


Le service git est accessible via SSH (voir [[#methodes_d_acces|ci-dessous]] pour les autres méthodes d'accès) :

^ Machine               ^ Nom                     ^ Role      ^ Contact                ^ utilisateur SSH     ^ Soft       ^
| riboul.faimaison.net  | git.faimaison.net       | Maître    | adminsys@faimaison.net | git                 | gitlab     |


==== Utilisation en lecture/écriture ====

Les dépôts publics
=== Authentification ===

Les comptes sont gérés par Gitlab.

Pour contribuer, vous avez deux possibilités :

  * Utiliser l'interface Web de Gitlab
  * Utiliser vos outils, sur votre ordinateur. Dans ce cas, il vous faut une clé SSH pour contribuer (voir ci-dessous)

== Générer sa paire de clés SSH ==

Autant que possible, on se base sur des clés RSA sur 4096 bits :

<code>
  $ umask 077
  $ mkdir -p ~/.ssh/
  $ ssh-keygen -t rsa -b 4096 -f ~/.ssh/faimaison
    # <éventuellement entrer une passphrase>
</code>

Chaque utilisateur est responsable de sa clé privée ; placer une passphrase sur sa clé ssh est fortement recommandé.
Ceci a pour but d'empêcher un tiers d'utiliser votre clé (il lui faudra connaître votre passphrase).

Dès que vous avez votre paire de clé, il suffit d'ajouter votre clé **publique** (contenue dans le fichier terminant par .pub) dans votre compte Gitlab.

== Authentification à deux facteurs ==

Pour protéger votre compte Gitlab, vous pouvez activer l'authentification à 2 facteurs (2FA ; accessible dans les [[https://git.faimaison.net/profile/account|paramètres de votre compte]]).

Quand l'authentification à 2 facteurs est activée pour votre compte Gitlab, vous devrez entrer les informations suivantes pour vous connecter : 

  * votre nom d'utilisateur
  * votre mot de passe
  * un code à usage unique donné par l'application dont on parle ci-dessous

Pour obtenir un code à usage unique, il vous faut une application compatible "Google Authenticator", il en existe des libres comme [[https://f-droid.org/repository/browse/?fdfilter=freeotp&fdid=org.fedorahosted.freeotp|FreeOTP]]. 

=== Utilisation ===

== Par l'interface Web de Gitlab ==

https://git.faimaison.net

== Via vos outils Git installés sur votre machine ==

Fonctionnement : tout se fait en ssh. Si on essaie de se connecter directement :

  ssh -i ~/.ssh/faimaison git@git.faimaison.net
  
On obtient un message de bienvenue :

  PTY allocation request failed on channel 0
  Welcome to GitLab, CapsLock!
  Connection to git.faimaison.net closed.

Pour dire à ssh de toujours utiliser cette clé et cet utilisateur (et donc pour simplifier la vie à git), on peut mettre quelque chose du genre dans son fichier ''~/.ssh/config'' :

<file>
Host git.faimaison.net
    IdentityFile ~/.ssh/faimaison
    User git
</file>

Ensuite, il suffit de cloner comme d'habitude :

  git clone git@git.faimaison.net:faimaison-membres/membres.git
  
Pour trouver l'adresse du dépot, il suffit d'aller sur la page du dépôt (exemple https://gitlab.faimaison.net/faimaison-membres/membres) et de la récupérer ici :

{{ ::depot.png?direct&500 |}}

=== Création d'un nouveau dépôt ===

Pour créer un nouveau dépôt, vous pouvez-le faire via l'interface Web de [[gitlab|Gitlab]]

===== Troubleshooting =====

==== Erreur de connexion SSH ====

Si un message d'erreur du type :

  WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
  IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!

apparaît, il y a deux possibilités :

  * quelqu'un fait effectivement quelque chose de pas très sympathique entre vous et le serveur (spoofing DNS, man-in-the-middle, etc) → **mauvais présage**
  * la machine qui répond derrière ''git.faimaison.net'' a changé (basculement de l'esclave en maître, etc) → **innocent**

Si il s'agit du second cas (vérifiez ! il y a sûrement eu une annonce sur la liste de diffusion membres), il suffit de supprimer le //fingerprint// fautif du fichier ''~/.ssh/known_hosts'' :

  $ ssh-keygen -R git.faimaison.net

===== Documentation sur git =====

  * [en] http://schacon.github.com/git/gittutorial.html (tutoriel officiel) ;
  * [en] http://progit.org/ ;
  * [fr] http://www-cs-students.stanford.edu/~blynn/gitmagic/intl/fr/ ;
  * [en] https://git.wiki.kernel.org/articles/g/i/t/GitSvnCrashCourse_512d.html (pour les gens qui sont habitués à SVN).

====== Configuration de gitolite ======

===== Architecture =====

 FIXME

On utilise les fonctionnalités de réplication de ''gitolite''.
La machine ''git.faimaison.net'' représente le serveur maître, ''git-slave.faimaison.net''
représente le serveur esclave.

Chaque "push" sur le serveur maître est immédiatement répliqué sur le serveur esclave.
Vous pouvez aussi pousser sur le serveur esclave, auquel cas les modifications sont d'abord renvoyées sur le serveur maître.

Si jamais le serveur maître est inaccessible, on peut **lire** sur le serveur de secours, **mais pas** pousser de modifications.

Si l'on pense que le master restera inaccessible longtemps, il faut :
  * contacter l'administrateur du serveur esclave, afin qu'il passe ''gitolite'' en mode "maître". Ceci suffit pour pouvoir continuer à pousser sur le serveur de secours.
  * intervertir les enregistrements DNS de ''git.faimaison.net'' et ''git-slave.faimaison.net''.


===== Remise en route =====

FIXME

(Note aux administrateurs des services gitolite)

Si le master est down pour de bon, il faut passer le slave en master :

  * modifier le //~/.gitolite/conf/gitolite.conf// et échanger master/slave
  * faire un //gl-compile-conf// (peut nécessiter de placer certaines variables d'environnement)
  * si la modification est définitive, modifier dans le dépôt //gitolite-admin// le fichier //conf/gitolite.conf// et pusher sur le nouveau master.
  * quand le nouveau slave est disponible, modifier sa conf de la même façon