In InseeFrLab/utilitr-template: Templates for the utilitR Project

Configurer Git sur son poste de travail {#git-config}

Tâches concernées et recommandations

L'utilisateur souhaite versionner son projet depuis son poste de travail en ayant recours pour cela à un dépôt distant, disponible sur un espace type GitLab ou GitHub.

L'utilisation du logiciel Git en local, qui relève plutôt de l'usage quotidien du logiciel, est reportée dans une fiche dédiée (Utiliser Git avec RStudio).

::: recommandation Pour interagir avec un dépôt Git distant, l'utilisateur a le choix entre deux protocoles d'authentification : SSH ou HTTPS. Il est conseillé d'utiliser le protocole HTTPS qui est simple à configurer. Vous pouvez utiliser le protocole SSH si vous le souhaitez, mais il peut s'avérer difficile à configurer. Si vous utilisez l'authentification HTTPS, il est recommandé de s'authentifier avec des jetons personnels d'accès (personal access tokens*) plutôt qu'avec un login et un mot de passe. :::

Les différentes forges utilisables

Une r with_def("forge") est un espace informatique en ligne qui accueille des dépôts distants. Un dépôt distant (remote repository en anglais) est un dossier que vous pouvez utiliser pour stocker vos codes (et leur historique), et pour partager des codes avec vos collègues ou stocker vos codes personnels.

Une forge prend généralement forme d'un site internet. Il existe deux forges principales :

• GitHub (accessible sur le Web, à l'adresse https://github.com), qui appartient à Microsoft ;
• GitLab qui se décline sous différentes formes :
  • une version publique, disponible sur https://gitlab.com, qui propose les fonctionnalités principales de versionnage du code mais également des fonctionnalités supplémentaires (discussions, mise à disposition de machines (runners) pour tester des scripts...) ;
  • des versions internes, qui reprennent la majorité des fonctionnalités de la version publique mais proposent des machines (appelées runners) internes. Celles-ci ne sont pas forcément ouvertes sur internet.

Les forges proposent des fonctionnalités précieuses pour gérer un projet impliquant du code ou de la documentation. La formation Travail collaboratif avec R décrit ces fonctionnalités de manière plus détaillée.

::: specificite Une forge interne GitLab est accessible depuis AUS. Son adresse, ainsi que des éléments complémentaires à cette fiche, sont disponibles dans la documentation AUS (Y:/Documentation/AUSV3/). :::

::: remarque Une instance GitLab est disponible sur le SSP Cloud [https://git.lab.sspcloud.fr/] avec laquelle peut interagir un service RStudio [lien vers fiche quand elle sera là], et vous pouvez l'utiliser si vous le souhaitez. Toutefois, le SSP Cloud est une plateforme accessible depuis Internet et a donc accès aux dépôts hébergés sur https://gitlab.com ou https://github.com. Il est donc conseillé d'utiliser une de ces deux r with_def("forges") plutôt que https://git.lab.sspcloud.fr/. :::

La suite de cette fiche décrit l'utilisation d'un dépôt distant sur une forge de type GitLab. Néanmoins, la procédure pour configurer l'interaction avec un dépôt distant situé sur GitHub est très similaire, ce qui est illustré dans la fiche Utiliser Git avec RStudio.

Installer Git sur son poste de travail {#git-install}

Pour interagir avec un dépôt distant sur GitLab ou GitHub, il est nécessaire d'utiliser l'outil de contrôle de version Git.

Avant d'essayer d'installer Git, le premier réflexe est de vérifier qu'il n'est pas déjà disponible. En effet, sur un serveur partagé comme AUS, ou sur une architecture comme le SSP Cloud, il n'est pas nécessaire d'installer Git puisque celui-ci est déjà disponible et configuré.

Si Git n'est pas disponible, il faut l'installer. Pour ce faire, il suffit de télécharger le logiciel site web officiel, puis de l'installer. Une fois le logiciel installé, il est possible de le retrouver dans le menu Démarrer, rubrique Git. L'utilisateur y trouvera plusieurs outils, dont un outil de ligne de commande (Git Bash) et une interface (Git GUI).

Interaction avec un dépôt distant : principe

[METTRE UN JOLI SCHEMA A PARTIR DE COLLABORATIF QUAND IL SERA PRET]

Git est un système décentralisé de contrôle de version : les codes sont modifiés par chaque agent sur son poste de travail, puis sont mis en conformité avec la version collective disponible sur le dépôt distant au moment où l'agent le décide.

Il est donc nécessaire que la forge connaisse l'identité de chacun des contributeurs, afin de déterminer qui est l'auteur d'une modification apportée aux codes stockés dans le dépôt distant. Pour que GitLab reconnaisse un utilisateur proposant des modifications, il est nécessaire de s'authentifier (un dépôt distant, même public, ne peut pas être modifié par n'importe qui). L'authentification consiste ainsi à fournir un élément que seul vous et la forge sont censés connaître : un mot de passe, une clé compliquée, un jeton d'accès...

Plus précisément, il existe deux modalités pour faire connaître son identité à GitLab :

• une authentification HTTPS (décrite ici) : l'authentification se fait avec un login et un mot de passe (qu'il faut renseigner à chaque interaction avec le dépôt), ou avec un token (méthode à privilégier).
• une authentification SSH : l'authentification se fait par une clé cryptée disponible sur le poste de travail et que GitHub ou GitLab connaît. Une fois configurée, cette méthode ne nécessite plus de faire connaître son identité : l'empreinte digitale que constitue la clé suffit à reconnaître un utilisateur.

::: conseil Si vous utilisez l'authentification HTTPS, il est conseillé d'utiliser un jeton d'accès. Celui-ci permet de s'authentifier, est facilement révocable et ne bénéficie pas des super-pouvoirs qu'octroie un mot de passe comme changer le nom d'un dépôt voire le supprimer. Plus d'éléments sur les jetons d'accès sont disponibles ici. :::

::: remarque Ne jamais stocker un token, et encore moins son mot de passe, dans un projet. Il est possible de stocker un mot de passe ou token de manière sécurisée et durable avec le credential helper de Git. Celui-ci est présenté par la suite.

S'il n'est pas possible d'utiliser le credential helper de Git, un mot de passe ou token peut être stocké de manière sécurisé dans un système de gestion de mot de passe comme Keepass. :::

La méthode SSH peut être laborieuse à mettre en place, mais elle confortable dans le travail quotidien car elle permet de ne pas avoir à renseigner son login et son mot de passe à chaque interaction avec le dépôt distant. Cependant, la méthode HTTPS est préférable car :

• elle est beaucoup plus légère à configurer. L'utilisation d'un système de mémoire du mot de passe, à savoir le credentiel helper, est beaucoup plus simple à mettre en place que la génération de clés SSH ;
• elle n'est pas bloquée par des pare-feux, contrairement à la méthode SSH. Par exemple, il est impossible sur un poste Insee d'interagir avec un dépôt sur https://gitlab.com ou https://github.com en SSH ;
• il est possible de conserver en mémoire ses identifiants (grâce au git credentials helper) pour ne pas avoir à les renseigner à chaque fois.

Configurer l'accès à dépôt distant en HTTPS {#git-connexion-https}

::: specificite

Pour pouvoir utiliser l'authentification HTTPS avec le Gitlab interne de l'Insee, il est nécessaire de modifier un paramètre relatif aux certificats SSL. Pour cela, ouvrir la ligne de commande Git (démarche expliquée dans la fiche Utiliser Git avec RStudio) et taper la commande suivante:

git config http.sslVerify false

Il est également possible d'utiliser l'authentification SSH

:::

Démarche générale

Pour interagir avec un dépôt distant en utilisant le protocole HTTPS, il suffit de configurer le mot de passe dans GitLab, en allant dans Preferences > Password, comme indiqué dans la capture d'écran ci-dessous :

utilitr::include_image("./pics/config_git/password_conf.png", compression = FALSE)

Une fois le mot de passe configuré, il ne reste plus qu'à r with_def("cloner") le dépôt distant sur lequel on veut travailler, par exemple depuis RStudio, suivant le protocole décrit dans la fiche Utiliser Git avec RStudio, en ayant pris soin de sélectionner l'URL correspondant au protocole HTTPS, comme ci-dessous :

utilitr::include_image("./pics/config_git/clone_https.png", compression = FALSE)

Au moment du clônage, l'utilisateur est invité à entrer son identifiant (celui de son profil Gitlab avec lequel il accède au dépôt distant), ainsi que son mot de passe (celui qu'il aura donc spécifié dans son compte GitLab) auquel on substituera un token.

::: conseil Selon le niveau de visibilité fixé par le propriétaire du dépôt distant, il est possible qu'il ne soit pas nécessaire de s'identifier au moment du clônage (c'est le cas pour les dépôts publics). En revanche, si le niveau de visibilité du dépôt est plus élevé (niveau privé), il se peut qu'il soit impossible à l'utilisateur de clôner le dépôt ; dans ce cas, il ne lui sera pas non plus possible de visualiser ce dernier dans GitLab. Il faut alors contacter le propriétaire du dépôt pour lui en demander l'accès. :::

Définir un jeton d'accès sur Gitlab

Dans GitLab, en haut à droite de la page, cliquer sur Edit profile :

utilitr::include_image("./pics/config_git/config_pat_gitlab1.png", compression = FALSE)

Dans le bandeau à gauche, cliquer sur Access Tokens :

utilitr::include_image("./pics/config_git/config_pat_gitlab2.png", compression = FALSE)

Choisir un nom (par exemple PAT_GITLAB, mais ce n'est pas un nom obligatoire) et des droits associés. Les droits read_repository et write_repository permettent d'effectuer les opérations standard (pull et push) décrites dans la fiche Utilisation Git avec RStudio.

utilitr::include_image("./pics/config_git/config_pat_gitlab3.png", compression = FALSE)

Après avoir validé, le jeton s'affiche afin de la récupérer et le stocker dans un endroit sécurisé (par exemple un gestionnaire de mot de passes). Attention, ce sera la seule fois qu'il sera visible.

utilitr::include_image("./pics/config_git/config_pat_gitlab4.png", compression = FALSE)

Plus bas sur la page, il est possible de voir l'ensemble des jetons utilisés, la date de dernière utilisation. C'est aussi ici que peut être supprimé le jeton en cas de doute sur sa confidentialité.

utilitr::include_image("./pics/config_git/config_pat_gitlab5.png", compression = FALSE)

::: remarque La marche à suivre pour créer un jeton d'accès sur GitHub est identique. La documentation officielle présente des captures d'écran qui illustrent la démarche. Il faut choisir le niveau repo pour avoir les droits mentionnés précédemment. :::

Garder en mémoire ses identifiants

L'authentification HTTPS implique en principe de renseigner ses identifiants (login et password, ou token) à chaque interaction avec le dépôt distant. Toutefois, Git propose un outil pour conserver temporairement en mémoire (cache) des informations d'authentification. Cette mise en mémoire est complètement optionnelle, et vous pouvez utiliser Git quotidiennement sans vous servir de cette possibilité.

La mise en mémoire se fait en deux temps:

• Il faut d'abord ouvrir une invite de commande Git Bash (explications ici) ;

• Il faut ensuite exécuter la ligne de code suivante pour stocker pendant quinze minutes les informations de connexion :

  ~~~~shell

  Sous windows

  git config --global credential.helper manager-core

  Sous mac et linux

  git config --global credential.helper ~~~~

::: remarque Si vous avez fait une faute de frappe dans le mot de passe ou dans le jeton, il est possible de vider la mémoire de la manière suivante, sous Mac ou Linux :

git config --global --unset credential.helper

Sous Windows, si vous avez utilisé l'option manager-core évoquée ci-dessus, vous pouvez utiliser une interface graphique pour effacer le mot de passe ou jeton erroné. Pour cela, dans le menu démarrer, taper Gestionnaire d'identification (ou Credential Manager si Windows ne trouve pas). Dans l'interface graphique qui s'ouvre, il est possible de supprimer le mot de passe ou jeton en question. Après cela, vous devriez à nouveau avoir l'opportunité de taper un mot de passe ou jeton lors d'une authentification HTTPS. :::

Configurer l'accès à dépôt distant en SSH {#git-connexion-ssh}

Pour interagir avec un dépôt distant en utilisant le protocole SSH, il faut créer une clé SSH, plus exactement une paire de chaînes de caractères, qui va permettre une authentification automatique auprès du dépôt distant. La version publique de la paire de clés est connue du dépôt distant ; la version privée reste quant à elle la propriété seule et unique de l'utilisateur. C'est l'association par un logiciel de cryptographie de ces deux versions qui permet l'authentification de l'utilisateur. ::: specificite L'authentification SSH ne fonctionne pas sur l'instance GitLab du SSP Cloud. Seule l'authentification en HTTPS est possible. :::

::: specificite La documentation d'AUS propose un tutoriel détaillé sur la configuration de la clé SSH. Vous pouvez le trouver ici : Y:/Documentation/AUSV3/Git_Utiliser Git sous AUSv3.pdf. :::

Générer une clé SSH

Un utilisateur peut générer autant de clés SSH qu'il le souhaite. Par exemple, vous pouvez générer une clé SSH par projet sur lequel vous travaillez (même si l'utilité de cette méthode n'est pas évidente).

Voici comment créer une clé SSH avec Git Bash :

• Il faut d'abord ouvrir une invite de commande Git Bash (explications ici) ;
• Il faut ensuite exécuter la ligne de code suivante :

utilitr::include_image("./pics/config_git/ssh_keygen.png", compression = FALSE)

La clé est générée sur le chemin spécifié et sera constituée de deux fichiers texte :

• un fichier dont le nom se termine par .pub (comme Public Key) qui fournit la partie publique de la clé, et qui a vocation à être diffusée (donc c'est ce fichier qu'on chargera sur Gitlab pour permettre l'authentification) ;
• un fichier dont le nom se termine par .ppk (comme Private Key) qui est la partie privée de la clé, et qui ne doit être diffusée en aucun cas.

La version privée de la clé doit être localisée dans un dossier caché que Git va automatiquement utiliser (en général un dossier .ssh localisé sur un dossier personnel).

Ajout de la clé SSH sous GitLab

Pour copier la partie publique de la clé sous GitLab, il faut aller dans la partie Settings de l'espace personnel sous GitLab, puis sélectionner "SSH Keys" sur le bandeau latéral gauche. On se trouve face à une fenêtre de texte comme ceci :

utilitr::include_image("./pics/config_git/ssh_key_record.png", compression = FALSE)

dans laquelle on doit copier-coller le texte que l'on trouve dans le fichier .pub de la clé SSH (en prenant soin d'éliminer l'éventuel texte en fin du type "imported-openssh-key").

GitLab est désormais configuré, et il est alors possible de faire dialoguer Git et GitLab en suivant, par exemple, les routines proposées dans la fiche Utiliser R avec RStudio.

Références

• formation Travail collaboratif avec R ;
• Happy Git with R.

InseeFrLab/utilitr-template documentation built on Oct. 21, 2022, 11:42 p.m.