Skip to content

Latest commit

 

History

History
345 lines (203 loc) · 16.7 KB

README.md

File metadata and controls

345 lines (203 loc) · 16.7 KB

Tutoriel GitLab Work in progress

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.

Sommaire

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.

https://www.atlassian.com/git/tutorials/using-branches/git-merge

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.

register

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.

creer depuis menu

creer depuis accueil

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

options 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.

options membres

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 membres

Options du projet

Un certain nombre d'options permettent de personnaliser le projet

options du 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"

projet-bookmark

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

Accueil du projet

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.

URL du projet

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).

Fourcher un projet

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 :

projet-ajouter-fichier

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

projet-editer-fichier

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 [email protected]:/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 :

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 :

issues-menu

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

issues-list

Pour créer une issue :

issues-new

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.

issues-boards

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

issues-milestones

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