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

Configuration de l’accès à GitLab

Se connecter à GitLab

  • Rendez-vous sur la ForgeMIA 
  • 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 (~/.ssh/id_ed25519.pub) qui est générée ou retenir le chemin d’accès à la clé

  • 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

  • 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 Profile, 2) SSH Keys, puis cliquer sur Add new key
    1. Coller la clé publique générée précédemment
    2. Renseigner le nom associé à la clé
    3. 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
  • automatisation (rapports, tests, compilation, déploiement de sites)
  • 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@forgemia.inra.fr:<namespace>/<projet>.git

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

Cloner le dépôt distant en local avec

git clone git@forgemia.inra.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.

Envoyer un dépôt local vers la forge

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

# on initialise le dépôt Git en indiquant que la branche principale doit s'appeler main
git init --initial-branch=main

# on synchronise notre dépôt git avec le dépôt GitLab
git remote add origin git@forgemia.inra.fr:<namespace>/<projet>.git

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

# 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

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

cd <projet>
git init
git checkout -b main
git remote add origin git@forgemia.inra.fr:<namespace>/<projet>.git
git add .
git commit -m "Initial commit"
git push -u origin main

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.

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.

Statut 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 :

  • guest : invité, consultation uniquement
  • reporter : suivi et contribution au projet sans coder
  • developer : contribuer au code sans configurer le projet GitLab
  • maintainer : contribuer au code et configurer le projet GitLab
  • owner : pour le transfert de propriété du projet

Attention

Donner le rôle d’owner à un membre lui laissera le droit de pouvoir supprimer le 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 ForgeMIA, 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 (si template existant)
  • Description
  • Assignation
  • Labels

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

Si il existe, permet de sélectionner un template d’issue.

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 :

Assignation

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

Labels

Permet de :

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

Pour créer un label :

Pratique

Scénario 1

Sur votre projet, déclarez un bug :

  • J’ouvre une issue
  • Je la commente 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 la commente 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…

Gestion des étiquettes sur un dépôt distant

Avec RStudio

Utiliser le Shell (Tools > Terminal > New Terminal) avec la ligne de commande.

En ligne de commande

Transférer :

Transférer une étiquette depuis un dépôt local :

git push origin [nom-du-tag]

Transférer toutes les étiquettes depuis un dépôt local :

git push origin --tags

Supprimer

Supprimer une étiquette sur un dépôt distant :

git push origin --delete v1.4-lg

Avec VS Code

  • Cliquer sur Aide > Afficher toutes les commandes ou utiliser le raccourci F1 ou Ctrl+Maj+P.
  • Saisir Git: Push Tags
  • Appuyer sur Entrée

ou utiliser le Terminal avec la ligne de commande.

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)