Sur cette page, vous trouverez des explications sur ce qu'est un contrôleur de version Git, comment créer vos propres dépôts Git sur les plateformes GitHub et GitGenes, ainsi que la manière de les paramétrer pour les associer à vos services datalab Onyxia.
Cela vous permettra entre autres de cloner, sauvegarder vos données stockées sur vos services, et ainsi garantir une gestion efficace de vos travaux.
## Mise en garde
Avant de vous détailler tout sur le contrôleur de version Git, nous voulons vous rappeler via ce paragraphe que quand vous créez un service sur le datalab Onyxia, aucunes des données que vous importer sur les services n'est persistantes, sauf pour les services de bases de données (Postgresql, Mongodb, etc…) qui eux, disposent d'un stockage persistant.
Les services du Datalab fonctionnent sur le modèle des conteneurs éphémères : dans un usage standard, l'utilisateur lance un service, réalise des traitements de données, sauvegarde le code qui a permis de réaliser ces traitements, et supprime l'instance du service.
Vous avez donc deux choix, celle que nous préconisons aux utilisateurs est d'automatiser ce processus d'import/export/synchronisation de données en utilisant un contrôleur de version Git qui vous sera entièrement expliqué sur cette page à la suite de ce paragraphe de mise en garde.
Ou d'importer manuellement vos données à la création de votre service puis de télécharger les données stockées sur vos services avant chaque arrêt d'utilisation.
Git, qui est la méthode que nous préconisons, est un système de gestion de version qui permet aux utilisateurs de suivre l'évolution de leurs fichiers au fil du temps, le plus connu étant GitHub.
Dans le cadre de nos services, nous simplifions ce processus : tous les utilisateurs ayant un compte ENSAE se voient automatiquement attribuer un compte GitGenes.
GitGenes est notre système Git hébergé en interne, utilisant la solution Gitea et offrant des fonctionnalités similaires à celles de GitHub ou GitLab. Il facilite la création, la gestion et la collaboration autour de dépôts Git, <ahref="https://code.groupe-genes.fr/ "target="_blank">celui-ci est disponible ici</a>.
Sacher que par défaut, le datalab Onyxia est préconfiguré avec votre compte <ahref="https://code.groupe-genes.fr/ "target="_blank">GitGenes</a>.
Les utilisateurs n'ont plus qu'à créer un dépôt sur leur compte GitGenes, puis, spécifier l'URL de ce dépôt dans nos services datalab Onyxia. Cela permettra qu'à la création d'un service, les données stockées sur votre dépôt seront automatiquement clonées sur votre service datalab Onyxia.
-<ahref="https://documentation-dsit.lab.groupe-genes.fr/Services/Datalab/Onyxia/#git-config"target="_blank">Où ajouter l'URL d'un dépôt Git lors de la configuration de vos services du datalab Onyxia</a>
-<ahref="https://documentation-dsit.lab.groupe-genes.fr/Services/Datalab/Onyxia/version/#creation-recuperation-de-lurl-dun-depot"target="_blank">Comment créer et récupérer l'URL d'un dépôt sur GitGenes ou Github</a>
Le Datalab est une plateforme mutualisée : les ressources utilisées par les services sont partagées entre les différents utilisateurs. A ce titre, les services du Datalab fonctionnent sur le modèle des conteneurs éphémères : dans un usage standard, l'utilisateur lance un service, réalise des traitements de données, sauvegarde le code qui a permis de réaliser ces traitements, et supprime l'instance du service. Cette sauvegarde du code est grandement facilitée par l'usage du contrôle de version.
Cette considération de performance ne doit cependant pas être vue comme une contrainte : le contrôle de version est une bonne pratique essentielle de développement. Les bénéfices sont nombreux, aussi bien à titre individuel :
* le projet local est synchronisé avec un serveur distant, rendant la perte de code quasi impossible ;
* l'historique complet des choix et modifications effectuées sur le projet est conservé ;
* l'utilisateur peut parcourir cet historique pour rechercher les modifications qui ont pu créer des erreurs, et décider à tout moment de revenir à une version précédente du projet, ou bien de certains fichiers.
Dans le cadre de projets collaboratifs :
* le travail simultané sur un même projet est possible, sans risque de perte ;
* l'utilisateur peut partager ses modifications tout en bénéficiant de celles des autres ;
* il devient possible de contribuer à des projets open-source, pour lesquels l'usage de Git est très largement standard.
!!! warning
Ce tutoriel vise à présenter comment le contrôle de version peut être facilement implémenté grâce aux outils présents sur le Datalab. Il ne présente pas le fonctionnement de Git et présuppose donc une certaine familiarité avec l'outil. De nombreuses ressources en ligne peuvent servir d'introduction ; l'utilisateur de R pourra par exemple consulter <ahref="https://linogaliana.gitlab.io/collaboratif/git.html"target="_blank">ce guide</a>. Une formation complète à Git sera bientôt proposée dans l'espace formation du Datalab qui sera bientôt ajouter sur notre Datalab Onyxia.
## Intégration de Git avec le Datalab
### Pourquoi Git ?
Bien qu'une utilisation hors-ligne de Git soit possible, tout l'intérêt du contrôle de version réside dans la synchronisation de la copie locale d'un projet (_clone_) avec un dépôt distant (_remote_). Différents services de forge logicielle permettent cette synchronisation des projets Git, dont les plus connus sont <ahref="https://github.com"target="_blank">Github</a> et <ahref="https://about.gitlab.com"target="_blank">GitLab</a>. Dans la mesure où le premier dispose aujourd'hui de beaucoup plus de visibilité — par exemple, les dépôts du Genes, sont hébergé en interne via Gitea <ahref="https://code.groupe-genes.fr/"target="_blank">accessible ici</a>.
Vous disposer donc automatiquement d'un dépôt <ahref="https://code.groupe-genes.fr/"target="_blank">GitGenes</a>, que vous pouvez accéder en utilisant votre compte ENSAE. Celui-ci est également automatiquement intégré sur votre compte du datalab comme <ahref="https://documentation-dsit.lab.groupe-genes.fr/Services/Datalab/Onyxia/#services-externes"target="_blank">décrit ici</a>.
le Datalab propose une intégration facilitée avec Git, que nous vous présentons à travers ce tutoriel. La suite du guide vous permettra de configurer GitHub & GitGenes sur le datalab à deux endroits:
- Dans l'onglet <ahref="https://onyxia.lab.groupe-genes.fr/account/third-party-integration"target="_blank">Services externes</a> qui ajoutera la configuration de votre dépôt git automatiquement sur chaques service qui vous créé (plus d'information sur notre <ahref="https://documentation-dsit.lab.groupe-genes.fr/Services/Datalab/Onyxia/#services-externes"target="_blank">guide principal ici</a> )
- Lors de la création d'un <ahref="https://onyxia.lab.groupe-genes.fr/my-services"target="_blank">Services</a>
Le guide montre en détail comment récupérer les informations suivantes sur Github & GitGenes:
- Nom d'utilisateur pour Git
- Email pour Git
- Jeton d'accès personnel (Token)
- URL Repository
!!! tip
La suite du tutoriel nécessite de disposer d'un <ahref="https://github.com/join"target="_blank">compte GitHub</a> ou <ahref="https://code.groupe-genes.fr/"target="_blank">GitGenes</a>.
!!! info
Si l'utilisation du Datalab avec la plateforme GitHub & GitGenes est facilitée, elle n'est en aucun cas obligatoire : il reste tout à fait possible d'utiliser la forge logicielle de son choix pour la synchronisation des projets.
### Récuperer votre nom d'utilisateur et email
=== "Github"
Votre nom d'utilisateur et email sont directement récupérable sur <ahref="https://github.com/settings/emails"target="_blank">ce lien</a> (paramètres utilisateur puis "Email").
=== "GitGenes"
Vous retrouverez automatiquement votre nom d'utilisateur dans votre <ahref="https://code.groupe-genes.fr/user/settings"target="_blank">compte GitGenes disponible ici</a> (paramètres utilisateur).
Votre nom d'utilisateur sera systématiquement composé tout attaché de la première lettre de votre prénom + votre nom + "-ensae" exemple:
- Nom: Houdin ; Prenom: Christophe
- Nom d'utilisateur: hchristophe-ensae
### Créer un jeton d'accès (_token_)
Le jeton d'accès n'est affiché q'une seul fois après sa création et n'est plus récupérable par la suite. Si vous perdez votre token vous devrer simplement en recréé un :
=== "Github"
La synchronisation avec un dépôt distant nécessite une authentification auprès de GitHub. Celle-ci s'effectue à l'aide d'un jeton d'accès personnel, qui doit être généré à partir du compte GitHub de l'utilisateur. Le service de génération est accessible à <ahref="https://github.com/settings/tokens"target="_blank">cette adresse</a>. La <ahref="https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token"target="_blank">documentation GitHub</a>(en Anglais) propose des illustrations pour guider le processus.
Pour générer un jeton, il est nécessaire de choisir un nom de jeton, un délai d'expiration et des droits d'accès (_scope_). Il est recommandé de choisir un délai court (30 jours) et un accès restreint (_repo_ seulement) afin de limiter les risques de sécurité en cas de diffusion malveillante du jeton.
<divstyle="text-align:center;">Configuration recommandée pour la génération d’un jeton d’accès GitHub</div>
=== "GitGenes"
Rendez vous sur directement sur le lien: <ahref="https://code.groupe-genes.fr/user/settings/applications"target="_blank">https://code.groupe-genes.fr/user/settings/applications</a>
Vous retrouverez un block "Générer un nouveau jeton", vous devrez:
- Ajouter un nom au jeton
- Spécifier si le token peu accéder soit à vos dépôts publique uniquement ou tout (public, privé et limité)
- Sélectionner les autorisations liées au token
Voici la configuration recommandée pour la génération d’un jeton d’accès GitGenes (modifier l'accès uniquement au "repository"):
Une fois le jeton généré, ce dernier apparaît à l'écran. Un jeton ne peut être visualisé qu'une seule fois ; en cas de perte, il faudra en générer un nouveau.
### Création & récupération de l'URL d'un dépôt
L'URL de vos dépôt vous sera demander lors de la configuration de vos service du datalab, celui-ci doit être spécifié afin que le service clone automatiquement votre dépôt sur votre service.
=== "Github"
Rendez vous sur <ahref="https://github.com/"target="_blank">Github</a>, cliquer en haut à droite sur l'image de votre profile et sélectionner "Your repositories"
Ici vous retrouver tous vos dépôts et pourrez en créer de nouveau en cliquant sur l'icône verte "new".
Pour récuperer l'URL, cliquer sur le dépôts que vous souhaitez cloner sur vos services du datalab vu précédemment. Sur la nouvelle page, cliquer sur le menu déroulant vert "<> code" puis copier l'URL https:
=== "GitGenes"
Pour la création d'un dépôt, rendez vous sur <ahref="https://code.groupe-genes.fr/"target="_blank">GitGenes</a>, cliquer en haut à droite sur l'icône "+" puis "Nouveau dépôt"
Pour la création d'un dépôt, rendez vous sur <ahref="https://code.groupe-genes.fr/"target="_blank">GitGenes</a>, cliquer en haut à droite sur l'image de votre profile puis sur "Profil":
Ici vous retrouverez vos différents dépôt personnel, cliquer sur le dépôt que vous souhaitez cloner sur vos services du datalab, sur la nouvelle page cliquer sur "copier l'URL" HTTPS:
### Ajouter les informations Git sur le Datalab
Nous avons vu précédemment les différentes informations nécessaires pour la configuration d'un dépôt GitHub & GitGenes sur le datalab. Nous allons maintenant voir où ajouter ces informations sur le datalab pour que vos dépôt soient clonés automatiquement sur vos services du datalab.
#### Nom d'utilisateur, email & jeton d'accès (token)
Ces informations peuvent être ajoutées à deux endroits différents:
- Sur l'onglet "Mon compte" qui va permettre d'ajouter un Git qui sera ensuite configuré par défaut sur chaque nouveau service que vous créerez, <ahref="https://documentation-dsit.lab.groupe-genes.fr/Services/Datalab/Onyxia/#services-externes"target="_blank">plus d'information ici</a>.
- Individuellement sur chaques services que vous créerez dans le sous onglet "Git" lors de la configuration du service, <ahref="https://documentation-dsit.lab.groupe-genes.fr/Services/Datalab/Onyxia/#git"target="_blank">plus d'information ici</a>.
#### Ajout de l'URL de dépôt
Pour que vos dépôt soit ajouter sur vos services, il faudra le spécifié l'URL de dépôt à chaque création d'un nouveau service L'URL de dépôt <ahref="https://documentation-dsit.lab.groupe-genes.fr/Services/Datalab/Onyxia/#git"target="_blank">détaillé ici</a>, penser donc à enregistrer la configuration de vos services afin de facilité la création récurente de vos services, plus de détails sur comment enregistrer et configurer un <ahref="https://documentation-dsit.lab.groupe-genes.fr/Services/Datalab/Onyxia/#configuration-general-du-catalogue-de-services"target="_blank">service ici</a>.
### Git via le terminal
Le jeton d'accès GitHub est disponible dans le terminal des différents services via la variable d'environnement `$GIT_PERSONAL_ACCESS_TOKEN`. Afin d'éviter de devoir s'authentifier à chaque opération impliquant le dépôt distant (_clone_, _push_&_pull_), il est recommandé de cloner celui-ci en incluant le jeton d'accès dans le lien HTTPS, à l'aide de la commande suivante :
où \<owner> et \<repo> sont à remplacer respectivement par le nom d'utilisateur et le nom du dépôt GitHub.
### Git via des interfaces graphiques intégrées
Les principaux services de production de code disponibles sur le Datalab disposent d'une interface graphique pour faciliter l'utilisation de Git :
* RStudio : RStudio propose une interface graphique pour Git native et assez complète. La <ahref="https://www.book.utilitr.org/03_fiches_thematiques/fiche_git_utilisation"target="_blank">documentation utilitR</a> présente son fonctionnement en détail ;
* Jupyter : le plugin <ahref="https://github.com/jupyterlab/jupyterlab-git"target="_blank">jupyterlab-git</a> permet un interfaçage (assez sommaire) de Jupyter avec Git ;
* VSCode : VSCode propose nativement une interface graphique très bien intégrée avec Git et GitHub. Une <ahref="https://code.visualstudio.com/docs/editor/versioncontrol"target="_blank">documentation détaillée</a>(en Anglais) présente les possibilités de l'outil.
Les interfaces graphiques facilitent la prise en main de Git, mais ne remplacent jamais complètement l'usage de l'outil via un terminal du fait d'une intégration nécessairement imparfaite. Il est donc utile de se familiariser avec l'usage de Git via le terminal le plus tôt possible.
