xac369/tutoriel-gitlab

Tutoriel GitLab

Ce guide collaboratif à l'ambition de vous donner les bases essentielles pour bien démarrer sur GitLab.

GitLab peut être utilisé en tant que SAAS, ou être installé sur votre propre instance privée.

NB: les traductions FR des interfaces ne sont pas toujours complètes.

Qu'est-ce que c'est, à quoi ça sert ?

GIT est un système de gestion de versions, qui permet de stocker de manière optimisée et sécurisée des fichiers et toutes leurs modifications dans le temps.

GIT est décentralisé, et permet à de multiples personnes de travailler ensemble sur le même projet, puis d'intégrer harmonieusement les travaux de chacun.

C'est un outil bas niveau (ligne de commande), mais on peut l'utiliser via des logiciels comme GitKraken par exemple.

Des sites webs comme GitHub ou GitLab (qui sont des "forges logicielles"), ajoutent à GIT des fonctionnalités telles que la gestion des "tickets" (issues), les releases, la documentation, l'intégration continue ou encore le déploiement automatisé, qui facilitent la collaboration, et en font une composante centrale pour atteindre l'agilité et les pratiques DevOps.

GitHub, c'est le site web (SAAS) qui a démocratisé l'usage de GIT, en lui ajoutant une surcouche web minimaliste mais permettant une collaboration facilitée. Il est devenu LA référence des développeurs pour tous les projets open-source populaires. Il fédère plus de 25 millions d'utilisateurs dans le monde qui collaborent tous les jours sur cette plateforme. https://fr.wikipedia.org/wiki/GitHub

GitLab, c'est une alternative open-source, idéale pour des usages privés ou plus avancés, et qui propose beaucoup plus de fonctionnalités. Le projet est financé par de nombreuses entreprises (dont Google Ventures) et est proposé en version CE : Community edition (gratuite) ou Entreprise pour bénéficier de fonctionnalité très avancées et de support. https://fr.wikipedia.org/wiki/GitLab_CE

Un glossaire est disponible à la fin de ce document

Comment fonctionne GIT

GIT maintient dans votre projet des fichiers d'index qui stockent chaque modification de fichier, ainsi qu'un lien vers la version précédente.

Ainsi, à chaque "commit" (modification de fichier(s)), vous enregistrez les nouvelles modification dans l'index.

Et vous pouvez revenir en arrière à tout moment, ou créer des "branches" qui vous permettront de travailler en parallèle sur une nouvelle version du fichier.

Concrètement, à la racine de votre projet, git maintient un dossier .git qui contient les indexes et le fichier de config.

Sécurité

Les autorisations d'accès aux projets sont gérées par les propriétaires des projets dans GitLab.

Vous ne devez pas mettre de mot passe ou donnée sensible dans les projets.

Inscription

Vous êtes autonome pour créer un compte sur la plateforme.

Merci de respecter la convention prenom.nom lors de votre enregistrement.

Une fois votre compte créé, vous pouvez créer des projets comme bon vous semble dans votre espace personnel.

Le nommage des projets par groupe doivent respecter des conventions de nommage.

Créer un projet

Créer un projet, c'est créer un espace public ou privé ou vous pouvez versionner des fichiers et collaborer.

Lorsque vous créez un nouveau projet, il peut résider :

soit dans votre espace personnel : https://[URL]/prenom.nom/nom-du-projet
soit dans un groupe existant : https://[URL]/groupe/nom-du-projet

Plusieurs options de visibilité sont disponibles :

Visibilité	Invité
Privé	Vous serez le seul à pouvoir accéder au projet et à donner des permissions à l'unité
Interne	Seuls les utilisateurs authentifiés peuvent voir le projet
Public	N'importe qui, même non authentifié peut voir le projet

Une fois le projet crée, vous pouvez commencer à l'utiliser.

Si le projet est privé, vous pouvez inviter des utilisateurs à collaborer.

Vous pouvez inviter des utilisateurs individuellement, ou par groupe.

Role	Permissions
Guest	Lire et commenter les issues
Reporter	Gérer les issues, voir le code
Developer	Modifier les fichiers, issues
Master	Administration du projet

Cf permissions

Options du projet

Un certain nombre d'options permettent de personnaliser le projet

Parmi les options réglables, vous pouvez :

personnaliser le logo, description, tags du projet
régler les permissions d'accès
activer/désactiver les issues/pipelines/wikis/snippets si vous n'en avez pas besoin (cella allège l'affichage)

Accueil du projet

Cette page permet d'avoir toutes les informations sur le projet.

Le fichier README.md est automatiqueemnt affiché et doit permettre de comprendre les tenants et les aboutissants du projet, ainsi que les moyens pour installer le projet ou collaborer.

Si le projet vous intéresse, mettez-le en favori pour le retrouver facilement sur la page d'accueil ou dans le menu"

Exemple de page d'accueil d'un projet GitLab :

L'URL présentée en haut du projet, qui peut-être de type HTTPS ou SSH permet de pouvoir clôner le projet, pour le rappatrier sur sa machine par exemple.

Fourcher (forker) un projet

Pour contribuer à un projet sur lequel nous n'avons pas les droits en écriture, il est d'usage de fourcher le projet, d'apporter les modifications (corrections ou améliorations) dans votre propre copie du projet, puis d'envoyer cette contribution en tant que merge request au projet original (qu'on appelle upstream).

Vous pouvez fourcher un projet depuis la page web du projet, c.a.d. le copier, soit dans votre espace personnel, soit dans un groupe pour lequel vous avez les permissions suffisantes.

Une fois fourché, vous êtes en possession d'une copie du projet sur laquelle vous pouvez travailler indépendamment puis éventuellement soumettre des contributions utiles au projet d'origine (upstream)

Gestion des fichiers

Les fichiers d'un repository peuvent être modifiés de multiples façons :

Via le site web : facile et rapide
Via un logiciel dédié : permet de travailler sur son poste indépendemmant avant d'envoyer les changements
Via le CLI GIT : permet de comprendre le fonctionnement de GIT et de travailler très précisément

Les 3 approches sont décrites ci-dessous.

Via l'interface web

GitLab propose une interface web riche d'où il est possible de faire beaucoup de choses :)

Pour créer, envoyer un fichier ou un dossier :

Pour modifier un fichier, ouvrez le fichier en cliquant sur son nom, puis cliquez sur "Edit"

Vous accédez alors à un éditeur de texte qui permet de modifier le fichier.

Une fois le fichier envoyé ou modifié, vous devez le "commit", c'est à dire sauvegarder vos changements et les décrire brièvement.

ex: "doc: mise à jour des informations d'installation"

💡 Des conventions de commit permettent de standardiser les messages et de générer des changelogs.

GitLab : Via un logiciel UI

On peut également travailler sur les fichiers directement sur son ordinateur, sans passer par l'interface GitLab.

Pour cela on peut utiliser l'un des nombreux clients GIT du marché. Le plus "simple" est GitHub for desktop

On va d'abord cloner le projet (copier en local).
Puis faire les modifications en local
Faire un commit
Envoyer le code sur GitLab (push)

GitLab : via le CLI GIT

La ligne de commande GIT est cryptique, mais il y a peu de commandes à connaitre; les connaitre vous permettra de mieux comprendre le fonctionnement de GIT pour mieux en tirer profit.

💡 Apprenez le CLI en 5 minutes avec try.github.io

Clé SSH

Pour utiliser le CLI, le plus simple est d'utiliser une clé SSH que vous associer à votre compte GitLab. Ceci permet de ne pas avoir à utiliser les mots de pass via le CLI.

générez la clé sur votre poste
- windows : avec putty
- mac/linux : ssh-keygen -t ecdsa -b 256
ajoutez la clé publique dans votre profil GitLab

Clone/Modif de repos

Les mêmes opération via le CLI (ligne de commandes) :

cloner un projet git clone git@gitlab..aaa.bbb.ccc:/prenom.nom/faq-generale.git
Ajouter les fichiers pour le commit git add question-1.md question-2.md
Sauvegarder les modifications : git commit -m 'ajout de questions'
Envoyer sur le serveur GitLab : git push

Demandes de fusion

Lorsque vous modifiez des fichiers sur un projet qui ne vous appartient pas, vous pouvez soumettre vos changements pour validation au propiétaire du projet.

Ceci permet de faire une revue, à l'issue de laquelle le propriétaire pourra directement intégrer vos changements dans le projet.

Améliorer ses textes avec le format markdown

Le format markdown permet d'enrichir facilement du texte brut. Dans GitLab, on peut écrire du markdown a peu près partout : fichiers .md, commentaires, issues...

Ce format est exploitable par de nombreux outils, qui permettent par exemple de générer des sites web.

Documentation complète ici : https://fr.wikipedia.org/wiki/Markdown

Quelques outils pratiques :

Un éditeur en ligne : dillinger.io
un tutoriel interactif : https://www.markdowntutorial.com/
Helper pour générer des tableaux : https://www.tablesgenerator.com/markdown_tables
Format mermaid pour générer des schémas : https://gitlab.com/gitlab-org/gitlab-ce/issues/3711

Les issues

Le système d'issues de GitLab est avancé et puissant !

Vous pouvez créez des catégories (tags), assigner les tâches, les estimer, gérer des roadmaps, ajouter des fichiers, commenter, recevoir des notifications, etc... un lieu idéal pour centraliser les discussions autour d'un projet et favoriser la collaboration transparente.

Pour accéder aux issues du projet :

Vous accédez alors à la liste des issues du projet

Pour créer une issue :

Créer une bonne issue est essentiel pour sa résolution. Chaque issue doit être explicite, avec un cas reproductible en cas de remontée de bug. Vous pouvez avoir quelques pistes pour rédiger un bon rapport de bug ici.

Agile

Les issues peuvent être organisées dans des "boards" type "kanban". Vous pouvez créer vos propres boards pour organiser vos priorités.

Les issues peuvent être groupés par "milestones" (sprints). Ceci permet de grouper des tâches pour en suivre la complétion.

GitLab : Les permissions

Les utilisateurs ont des permissions différentes selon le niveau d'accès qu'ils ont dans un groupe ou un projet particulier.

Si un utilisateur est à la fois dans le projet d'un groupe et le projet lui-même, le niveau d'autorisation le plus élevé est utilisé.

Quand on créé un projet, nous en sommes le "Owner", et accordons des permissions à d'autres membres si nécéssaire.

Permission	Invité	Reporter	Developer	Master	Owner
Issues	✔	✔	✔	✔	✔
Gérer les issues	⨯	✔	✔	✔	✔
Effacer une issue	⨯	⨯	⨯	⨯	✔
Lire le wiki	✔	✔	✔	✔	✔
Editer le wiki	⨯	⨯	✔	✔	✔
Commenter	✔	✔	✔	✔	✔
Edit un commentaire	⨯	⨯	⨯	✔	✔
Lire le code	⨯	✔	✔	✔	✔
Contribuer (merge request)	⨯	⨯	✔	✔	✔
git push	⨯	⨯	✔	✔	✔
Gérer l'équipe projet	⨯	⨯	⨯	✔	✔
Configurer les pages projet	⨯	⨯	⨯	✔	✔
Créer un projet dans groupe	⨯	⨯	⨯	✔	✔
Transférer un projet	⨯	⨯	⨯	⨯	✔
Effacer un project	⨯	⨯	⨯	⨯	✔
Voir les jobs	✔	✔	✔	✔	✔
Configurer les hooks	⨯	⨯	⨯	✔	✔
Voir les environments	⨯	✔	✔	✔	✔
Créer un environment	⨯	⨯	✔	✔	✔

cf documentation officielle

GitLab : Gestion de projet (boards)

[todo]

GitLab : Publier du contenu avec GitLab pages

[todo]

GitLab : Mirroring avec GitHub

[todo]

GitLab : Intégration continue

[todo]

FAQ

Clé SSH

[todo]

Liens

Glossaire

intégration continue : pratique qui consiste à vérifier chaque modification du code source pour prévenir les régressions. Le principal but de cette pratique est de détecter les problèmes d'intégration au plus tôt lors du développement. De plus, elle permet d'automatiser l'exécution des suites de tests et de voir l'évolution du développement du logiciel.
devops : mouvement visant à l'alignement de l'ensemble des équipes du système d'information sur un objectif commun, à commencer par les équipes de dev ou dev engineers chargés de faire évoluer le système d'information et les ops ou ops engineers responsables des infrastructures.
commit : Fait d'enregistrer dans un outil de gestion de versions une nouvelle version d'un ensemble de fichiers.
release : version fixée d'une réalisation
issue : Un ticket qui permet de définir une feature ou un bug.
repository : Un projet au sens GIT
origin : GIT étant décentralisé, origin est le nom conventionnel du serveur par défaut
upstream : Lorsque l'on copie (fork) un projet, upstream représente le repository d'origine par convention
fourcher/forker : copier intégralement un repository