Important

Attention, les captures d’écran faites sur GitLab proviennent d’une ancienne version de la forgeMIA. Cela ne devrait pas géner la compréhension et la bonne lecture des supports.

Les supports seront mis à jour au moment du passage à la forge institutionnelle.

Objectifs

Pratiquer

  • GitLab :
    • Présentation générale
    • Configuration des accès
    • Présentations des issues
  • Interactions avec un dépôt distant et son dépôt local

Rappels de la session 1

Rappels

Nous avons vu :

  • l’intérêt de l’usage d’un outil comme Git

  • les différents états d’un dépôt local

  • les commandes principales selon 3 modes :

    • en ligne de commande
    • avec RStudio
    • avec VS Code

Les commandes Git de base

  • Initialiser un dossier en dépôt local (git init)
  • Visualiser l’état d’un dépôt (git status)
  • Comment ne pas suivre certains fichiers (.gitignore)
  • Accepter des modifications (git add)
  • Enregistrer des modifications (git commit)
  • Bonnes pratiques pour les commits (atomique, message)
  • Consulter l’historique sur le dépôt (git log)
  • Annuler des modifications (git restore, git reset)
  • Voir des modifications (git diff)

Pré-requis pour cette session 2

Il est nécessaire d’avoir suivi la session 1 ou de connaître les commandes de base de Git.

Pratique

Choisissez un projet :

  • reprenez celui de la session 1
  • un autre projet existant avec un dépôt Git
  • créer un nouveau projet et initialiser le dépôt Git

Vous pouvez faire des modifications, commiter les modifications, parcourir l’historique… en ligne de commande, avec RStudio ou avec VS Code.

États

Les états du système de fichiers avec un repo distant :

Définitions

GitLab

GitLab est un logiciel libre développé par GitLab Inc. et utilisé sur la forge commerciale GitLab.Com

Forge majoritaire dans les installations au sein de l’ESR hal-04098702.

Forge

Définition

Une forge est une plateforme web simplifiant la mise en oeuvre de bonnes pratiques et facilitant le développement de logiciels de meilleure qualité, ainsi que la constitution de communautés de contributeurs et d’utilisateurs.

Une forge intègre :

  • outils de développement collaboratif (suivi des modifications du code, gestion des demandes et des réponses d’utilisateurs - tickets -, gestion des contributions, gestion du projet),
  • industrialisation du processus de création du logiciel à partir de son code source (compilation, tests automatiques, assurance qualité, diffusion des livrables),
  • outils de communication comme Mattermost.

hal-04098702

forge.inrae.fr

Pour les agents INRAE

forge.inrae.fr est une forge mise en place pour tout INRAE utilisant le logiciel GitLab, dans sa version Community Edition (CE).

Pour les étudiants et personnel de recherche UB

https://gitub.u-bordeaux.fr/est une forge mise en place par l’université de Bordeaux

Configuration de l’accès à GitLab

Se connecter à GitLab

  • Rendez-vous sur la Forge 
  • Connectez vous avec vos identifiants (LDAP) INRAE en cliquant sur “Connexion SSO”

Définition de SSH

SSH (Secure Shell) est un protocole réseau qui permet de :

  • connecter un utilisateur à un système distant,
  • authentifier un utilisateur,
  • chiffrer les communications.

Une paire de clés SSH est composée d’une clé privée et d’une clé publique.

Plus d’informations sur la page SSH de GitLab.

Création d’une paire de clés SSH

  • Ouvrir un terminal de commande

  • Taper la commande suivante

    ssh-keygen -t ed25519

  • Ne pas rentrer de mot de passe (optionnel)

  • Copier la clé publique qui est générée dans le fichier ~/.ssh/id_ed25519.pub (avec la commande précédente)

  • Tools > Global Options > Git/SVN
  • Create SSH key
  • Choisir le type de clé SSH : ED25519
  • Ne pas renseigner de mot de passe (optionnel)
  • Cliquer sur Create et RStudio va générer une paire de clés à l’emplacement indiqué

TODO

Git-Gui est installé sous Windows avec Git.

Menu Help > Show SSH keys

Important

  • Laisser le nom de fichier par défaut.
  • Ne jamais communiquer la clé privée (~/.ssh/id_ed25519).
  • La clé privée doit rester sur le poste où elle a été générée.
  • Ne pas la réutiliser sur un autre poste.

Dans GitLab

  • Dans GitLab, aller dans 1) Edit Profil, 2) SSH Keys, puis cliquer sur Add new key
    1. Coller la clé générée précédemment
    2. Coller la clé publique générée précédemment
    3. Renseigner le nom associé à la clé
    4. Ne pas saisir de date d’expiration

Projet GitLab

Création d’un projet dans GitLab

Aller sur la page d’accueil (cliquer sur le logo GitLab en haut à gauche) et cliquer sur le bouton “New project”.

Pour mettre sur GitLab un dépôt créé sur votre machine, cliquer sur “Create blank project”.

Paramètres du projet

On détermine le nom du projet (1) et son URL (2 et 3)

(1) : On détermine la visibilité du projet (accès restreint, accès à tous les utilisateurs authentifiés, ou public).

(2) : Pour avoir un projet vide, ne pas créer de README.

Votre premier projet est créé !

Pratique

Création d’un projet vide dans GitLab

  1. Se connecter sur l’interface GitLab
  2. Créer un nouveau projet vide avec les paramètres ci-dessous
  3. Observer les lignes de commandes proposées

Paramètres pour le nouveau projet

  • Project name : mon projet
  • group or namespace : celui de l’utilisateur
  • Visibility Level : private
  • Project Configuration : ne pas cocher la case d’initialisation du dépôt avec un README

Définition

Un projet sur GitLab contient :

  • un dépôt Git
  • une interface pour voir l’historique des commits
  • une interface pour visualiser les fichiers du dépôt
  • un système de tickets (dit “issues” ou ticket en français)
  • des membres
  • beaucoup, beaucoup d’autres choses…

Remarque générale

Important

Dans la suite de la présentation, les lignes de commande <namespace> et <projet> sont à remplacer par une valeur dépendante de votre contexte.

<projet>.git qui devra être remplacé par mon_projet.git si le projet s’appelle “mon_projet” !

Commandes initiales sur un nouveau dépôt

Deux possibilités

  • Je souhaite récupérer un dépôt distant en local
  • Je souhaite envoyer un dépôt local existant sur GitLab

Remarque

Les commandes sont affichées sur la page d’accueil du projet, lors de la création d’un dépôt vide. 3 cas :

  • cloner le dépôt en local, le modifier et l’envoyer
  • créer un dépôt local et l’envoyer
  • envoyer un dépôt local existant

Important

Assurez-vous de toujours utiliser les adresses de vos projets sous la forme suivante : (pas de https)

git@forge.inrae.fr:<namespace>/<projet>.git

Dépannage SSH

  • Lors de la première communication SSH avec le serveur, ce message apparaîtra :

    The authenticity of host 'forge.inrae.fr (147.100.165.25)' can't be established.
ED25519 key fingerprint is SHA256:eAAb7qrQGTT3kY6Iy5PXsVkd2YMxwK5VZlv0Cls63Vk.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])?

    Confirmer l’authenticité du serveur en tapant yes.

  • Si la clé n’est pas trouvée par git (problème rencontré suite à la génération d’une clé SSH par Git-Gui sur un poste Windows : sous VS Code le chemin de la clé recherché par git n’est pas le bon), configurer :

    git config core.sshCommand "ssh -i ~/.ssh/id_ed25519"

Récupérer un dépôt distant en local

Cloner le dépôt distant en local avec

git clone git@forge.inrae.fr:<namespace>/<projet>.git

Le dossier projet est créé en local et contient les fichiers du dépôt distant

Pour cloner un dépôt existant il faut créer un nouveau projet R et renseigner l’adresse SSH disponible dans le dépôt GitLab.

Après Create Project le dépôt GitLab sera disponible en local sur votre machine.

Il n’y a pas de menu pour cloner un dépôt. Utiliser la ligne de commande.

Rappels pour créer un dépôt

Pour connaître la version de Git : git --version.

# À faire une fois (fait dans la session 1) :
# pour que la branche principale s'appelle toujours main quand on initialise un dépôt Git
git config --global init.defaultBranch main

# Créer un dépôt local
## on se place dans le dossier pour lequel on souhaite versionner
cd <projet>

## on initialise le dépôt Git
git init

## on réalise un commit d'initialisation
git add .
git commit -m "Initial commit"

En cas d’erreur sur la commande git init, voir l’onglet Version de Git < 2.28.0.

# on se place dans le dossier pour lequel on souhaite versionner
cd <projet>

# on initialise le dépôt Git
git init
git checkout -b main

# on réalise un commit d'initialisation
git add .
git commit -m "Initial commit"

Envoyer un dépôt local vers la forge

# on se place dans le dossier pour lequel on souhaite versionner
cd <projet>

# on associe notre dépôt local avec le dépôt distant sur la forge
git remote add origin git@forge.inrae.fr:<namespace>/<projet>.git

# on pousse les modifications vers le dépôt distant
git push -u origin main

Les mêmes commandes sont disponibles sur la page d’accueil du projet GitLab, si celui ci est vide.

Pratique

Synchronisation d’un dépôt local sur la forge

Envoyer un projet local sur le dépôt GitLab que vous venez de créer.

Clonage d’un projet disponible sur GitLab

Cloner sur votre machine le dépôt situé à cette adresse.

Navigation dans un projet GitLab

La vue d’ensemble

  • Informations sur le dépôt (nb de commits, de branches, d’étiquettes, visibilité)
  • Dernier commit
  • Fichiers sur la branche main
  • Affichage du README.md

Fichiers

Vue des fichiers

Commits

Vue des commits

Étiquettes

Vue des étiquettes

Les issues

Une section dédiée est prévue un peu plus loin.

La configuration du projet

La majorité des options par défaut est adaptée.

On peut ajouter un logo et une description au projet dans Settings > General.

Gestion des membres d’un projet GitLab

Membres d’un projet

Par défaut seul le créateur du dépôt peut réaliser des modifications (commit).

Si dans le cadre d’une collaboration vous souhaitez travailler avec d’autres personnes il suffit de les ajouter comme membres de votre dépôt.

Rôle d’un membre

Les personnes qui auront accès à votre dépôt peuvent avoir différents rôles selon leur degré d’investissement dans le projet :

  • invité / guest : invité, consultation uniquement
  • planificateur / planner : planification et contribution au projet sans coder
  • rapporteur / reporter : suivi et contribution au projet sans coder
  • développeur / developer : contribuer au code sans configurer le projet GitLab
  • chargé de maintenance / maintainer : contribuer au code et configurer le projet GitLab
  • propriétaire / owner : pour le transfert de propriété du projet

Attention

Donner le rôle d’owner à un membre lui laissera le droit de pouvoir le projet et son dépôt…

Pour inviter d’autres utilisateurs à contribuer au projet, il faut les inviter :

Pour configurer le statut du membre :

Lorsqu’un utilisateur n’est pas connu de la forge, il faut lui demander de faire une première connexion sur l’adresse de la forge, avec son identifiant LDAP.

Il est alors connu de la forge et vous pouvez l’ajouter sur le projet.

Pratique

Inviter un membre sur un projet

Invitez au moins une personne présente aujourd’hui à la formation sur votre projet personnel.

Ajoutez là en tant que reporter (ça suffira pour aujourd’hui).

Les issues

Définition

Une issue est comme un ticket et permet de :

  • prendre des notes,
  • échanger sur une idée,
  • identifier un problème et le documenter,
  • structurer son plan de travail.

Plus d’informations sur les issues.

Pour créer une issue : Issues > New Issue

Ouvrir une issue

Paramètres d’une issue

Les paramètres d’une issue :

  • Titre
  • Type (ticket ou incident)
  • Description
  • Assignation
  • Labels
  • Date d’échéance (due date)

Paramètres d’une issue

Titre

Le titre permet d’avoir une vision rapide du problème ou de l’idée sur laquelle porte l’issue.

Type (ticket ou incident)

Incident : ticket modifié pour guider la résolution d’un incident, qualifié par sa gravité (inconnue… critique), son état (ouvert… résolu)

Description

Possibilité de sélectionner un modèle de description. La description permet de décrire en profondeur l’idée ou le problème rencontré. C’est le corps de l’issue.

Elle s’écrit en Markdown, voir Écrire en Markdown, Markdown dans GitLab.

Personne assignée / Assignee

Facultatif. Permet d’assigner une/des personnes qui sera/seront à même de résoudre l’issue.

Jalon / Milestone

Pour planifier la réalisation d’une tâche.

Date d’échéance / Due date

Pour indiquer une date butoir.

Labels

Permet de :

  • Catégoriser les issues à l’aide d’une couleur spécifique
  • Filtrer rapidement les issues

Pour créer un label :

Commentaires sur un ticket

Un ticket peut être commenté par les personnes ayant accès au projet (voir configuration du projet et gestion des membres).

Pratique

Scénario 1

Sur votre projet, déclarez un bug :

  • J’ouvre une issue
  • Je l’écris en y intégrant des captures d’écrans
  • J’assigne la/les personnes les plus à même à résoudre le problème
  • Je crée et j’attribue le label bug

Scénario 2

Sur le projet sur lequel vous avez été invité, proposez une nouvelle idée d’amélioration :

  • J’ouvre une issue
  • Je l’écris en y intégrant :
    • des bouts de codes existants pouvant aider au développement
    • des cases à cocher pour suivre l’avancement
  • Je m’assigne l’issue
  • Je crée et j’attribue le label nouvelle fonctionnalité

Lien avec les commits

  • Mentionner un commit dans une issue (ex. : « Le texte ajouté par commit 26171abf doit être complété… »).
  • Lier un commit à une issue par le message de commit. Le commit apparaîtra dans l’historique de l’issue
git add .
git commit -m "Correction orthographique. #12"
  • Fermer une issue par le message de commit
git add .
git commit -m "Correction orthographique. fixes #12"

mais aussi fix, close, resolve, implement…

Bonnes pratiques d’interaction

Contrôler où on en est

  • Après un moment d’absence, commencer par faire un git status
  • Si plusieurs personnes travaillent sur le même projet, commencer par un git pull (synchronisation du dépôt local).

GitLab usine à gaz

  • GitLab (son interface web) permet plein de choses mais faire simple !
  • Un bon projet n’exploite pas forcément toutes les fonctionnalités de GitLab

Où éditer ses fichiers ?

  • Même si GitLab le permet, ne pas modifier les fichiers depuis GitLab
  • Si fait, commencer par un git pull avant les premières modifications
  • Sinon, le prochain “push” sera refusé. Il faudra alors faire un pull et résoudre les éventuels conflits

Prochaine session

L’univers des branches !

  • Création (git branch)
  • Fusion (git merge)
  • Rebasage (git rebase)