1 Prérequis

1.1 Créer un compte sur un service web distant

Créer un compte sur GitHub
Fonctionne également avec GitLab tel que ForgeMIA (pour le personnel INRAE)

1.2 Installer git ainsi qu’une application graphique d’aide au développement

1.2.1 Installation de Git

Sur unix, git est installé par défaut.

git --version
## git version 2.25.1

Si vous êtes sur Windows, se référer à https://git-for-windows.github.io/

Suppléments : Happy git with R - 6: Install git

Sous MacOS , testez la commande

git --version
## git version 2.32.0 (Apple Git-132)

Si git n’est pas installé, une invit vous proposera de l’installer pour vous.

1.2.2 Installation de GitHub Desktop

Pour commencer, nous utiliserons GitHub Desktop.

Il existe de nombreux autres outils prenant en charge un gestionnaire de versions, tel-que RStudio, VSCode, GitKraken, Sublime Merge, …

1.3 Connexion entre la session local et le compte distant (sur github.com)

Entre GitHub Desktop et github.com, la synergie est maximale. On utilisera les même identifiants pour se connecter des deux cotés.
Note : sur les sessions stage des ordinateurs de formation, il peut être nécessaire de créer un trousseau

1.3.1 Clés SSH

Pour interagir avec le dépôt distant sans renseigner ses identifiants à chaque fois, on utilisera une clé ssh (Secure Shell). Elles vont par paires comme par exemple :
- id_rsa et id_rsa.pub
- id_ecdsa et id_ecdsa.pub
- id_ed25519 et id_ed25519.pub

Les clés sont généralement stocké dans le dossier ~/.ssh

Vérifier si l’on dispose déjà d’une paire de clés (elles sont dans le dossier ~/.ssh)

ls -al ~/.ssh

Si vous n’avez pas de clé existante, générer la paire de clés avec ssh-keygen :

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

L’authentification des opérations menées à partir de Git sur GitHub passe exclusivement par l’échange de clefs ssh. Il vous faut donc faire connaitre à GitHub votre clef publique en la copiant dans son interface.
Renseigner la clé publique sur GitHub, via l’interface graphique : https://github.com/settings/keys

cat ~/.ssh/id_rsa.pub

vérifier que tout fonctionne

 ssh -T git@github.com
# A la première connexion, vous pouvez voir un warning de ce type :
#> The authenticity of host 'github.com (IP ADDRESS)' can't be established.
#> RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
#> Are you sure you want to continue connecting (yes/no)?
# Verify that the fingerprint in the message you see matches GitHub's RSA public key fingerprint ( https://docs.github.com/en/github/authenticating-to-github/githubs-ssh-key-fingerprints ). If it does, then type yes:

## > Hi username! You've successfully authenticated, but GitHub does not provide shell access.

Procédure détaillée Mac, Windows, Linux

Pour aller plus loin sur le chiffrage asymétrique

1.4 Renseigner ses identifiants

Configuration des informations de l’utilisateur pour tous les dépôts locaux

Via les options de GitHub Desktop
Si vous utilisez git en ligne de commande

git config --global user.name "[nom]"
git config --global user.email "[email]"
git config --global color.ui auto

Si vous utilisez git avec R

usethis::use_git_config(user.name = "[nom]", user.email = "[email]")

Pour connaitre la configuration actuelle

git config --list

2 Versionner ses documents avec git

2.1 Créer un dépôt distant sur GitHub

Un dépôt est définit avec l’identifiant <username>/<repository> (ici CedricMidoux/migale2022)

Notez la première ligne avec l’adresse pour récupérer le dépôt en sélectionnant le mode SSH.

Remarque : Bien que cela soit parfois un peu plus délicat, il est aussi possible d’initier un dépôt localement avec git init mais dans ce cas il faudra ensuite lier ce dépôt à un remote distant si l’on le souhaite.

mkdir testRepo
cd testRepo
# Initialized empty Git repository in /Users/vloux/tmp/testRepo/.git/
git init
# Add a new local git repo to an existing and empty Github repo : 
git remote add origin git@github.com:vloux/testRepo.git
#Verify new remote
git remote -v
git branch -M main
git push -u origin main

2.2 Cloner le dépôt depuis GitHub vers la session locale

Via l’interface graphique, on sélectionne facilement notre dépôt.
Sinon on utilise le lien fourni avec le mode SSH.
En ligne de commande, on utilise git clone

git clone git@github.com:CedricMidoux/migale2022.git

Le dépôt est vide et disponible localement.

2.3 Ajouter un document (en local)

Ouvrir le dossier dans l’explorateur de fichiers
Ajouter un fichier README.md avec quelques lignes de texte.
Les modifications sont listées dans la colonne de gauche Change.
On ajoute les modifications a suivre avec les cases a cocher.
Lorsque l’on est satisfait on peut figer l’état avec un commit. On renseigne un message de commit explicite et Commit to main.
En ligne de commande on utilise git status pour connaître l’état de notre dépôt. git add pour ajouter un fichier a l’index, puis lorsque toutes les modifications sont suivies, on peut commit avec git commit.

2.4 Modifier un fichier et observer les différences

On modifie le fichier et observe ces différences dans le panel
En ligne de commande on utilise git status pour suivre comparer les versions.

2.5 Changer de branche

On travaille actuellement sur la branch principale main. On peut créer une nouvelle branche et changer de branche avec l’onglet dédié.

2.6 Pousser les modifications locales sur le dépôt distant

Pour l’instant les modifications sont juste en local, il est nécessaire de les envoyer vers le remote distant (server GitHub)
Ici encore, interface graphique nous facilite la tache avec l’onglet Publish branch
La commande git push pousse les modifications de la branche main (la branche par défaut locale) sur la branche origin (le nom de la branche distante). On peut aussi utiliser la version longue git push origin master
On peut lister les différents dépôts distants avec

git remote -v
# origin    git@github.com:CedricMidoux/migale2022.git (fetch)
# origin    git@github.com:CedricMidoux/migale2022.git (push)

2.7 Verification sur GitHub des modifications du dépôt

Connectez vous sur l’interface de GitHub :
- Trouvez votre dépôt
- Vérifiez que vous trouvez bien le fichier que vous avez modifié, les commits

2.8 Modification du dépôt par l’interface

Editez README.md depuis l’interface en ligne
Commitez la modification

2.9 Récupérer sur le repo local des infos de la branche distante

On récupère localement les modifications distante avec Pull origin (ou git pull) qu’il s’agisse de modifications faite en ligne ou par un collègue travaillant sur le même projet.

2.10 Le journal des modifications

On peut explorer les commit avec l’onglet History (ou git log).

git log
# commit 4606251a3f1a63874803c1a2397072b7ac60ebf1 (HEAD -> master, origin/master)
# Author: CedricMidoux <34483895+CedricMidoux@users.noreply.github.com>
# Date:   Mon Mar 8 11:30:27 2022 +0100
# 
#     Update README.md
# 
# ...

Pour chaque commit on a un identifiant (SHA), l’auteur, la date et le commentaire (d’où l’interet de correctement nommer ses commits)

2.11 Naviguer entre les commits

A partir de l’historique des commit, on peut revenir a une ancienne version avec Revert changes in commit
Si cela entraîne des conflits, il faut les traiter manuellement. On peut s’aider d’interface dédiée tel-que meld.
Sinon on peut également tirer une branche a partir d’un (ancien) commit pour travailler sur une fonctionnalité dédiée.
En ligne de commande, on utilise git checkout [SHA] ou git checkout [branch]

2.12 Nommer des versions (tags)

Pour fixer une version, communiquer plus facilement ou annoncer une modification majeure, il est courant d’utiliser des tags.
Sur l’interface en ligne de GitHub, on retrouve les tags.

2.13 Travailler à plusieurs - Issues

Posez une question a votre voisin de formation en utilisant le bouton New Issue

2.14 Travailler à plusieurs - Pull request

Via l’interface en ligne, créez une branche fork de votre voisin de formation.
Faites une modification
Créez une pull request et argumentez votre modification
Explorez les suggestions que vous avez reçu
Merge pull

3 Documents Computationel : Rédaction d’un notebook avec RStudio

Connectez vous au RStudio de migale.
Observer son profil git config --global --list

usethis::git_sitrep()
# Git config (global)
# • Name: 'Cedric Midoux'
# • Email: 'cedric.midoux@inrae.fr'
# • Global (user-level) gitignore file: '~/.gitignore'
# • Vaccinated: TRUE
# ℹ Defaulting to 'https' Git protocol
# • Default Git protocol: 'https'
# • Default initial branch name: <unset>
# GitHub
# • Default GitHub host: 'https://github.com'
# • Personal access token for 'https://github.com': <unset>
# • To create a personal access token, call `create_github_token()`
# • To store a token for current and future use, call `gitcreds::gitcreds_set()`
# ℹ Read more in the 'Managing Git(Hub) Credentials' article:
#   https://usethis.r-lib.org/articles/articles/git-credentials.html
# Git repo for current project
# ℹ No active usethis project


# Si besoin
usethis::use_git_config(user.name = "[nom]", user.email = "[email]")

Pour GitLab, on utilise la clé ssh publique (Tools > Global Options > Git > View public key) à renseigner sur son profil en ligne.

Depuis 2020, GitHub recommande l’utilisation de token personnel

usethis::create_github_token()
# • Call `gitcreds::gitcreds_set()` to register this token in the local Git credential store
#   It is also a great idea to store this token in any password-management software that you use
# ✔ Opening URL 'https://github.com/settings/tokens/new?scopes=repo,user,gist,workflow&description=DESCRIBE THE TOKEN\'S USE CASE'

gitcreds::gitcreds_set()

Clonez votre projet :
- New Project (en haut à droite)
- Version Control
- Git
- Repository URL (clone with SSH : https://github.com/<user>/<repository>.git) et Subdirectory : ~/work/TRAINING/
Explorez le dépôt depuis ce 3e device remote

Grâce à l’onglet git de Rstudio, vous pouvez suivre l’état des fichiers, commit, diff, push/pull, …

Complétez le .gitignore avec usethis::git_vaccinate()
Créez un document R Markdown :
- File
- New file
- R Markdown

Dans ce document on a :

Une entête générale
Du texte, mis en forme avec markdown
Du code R dans des chunks
Des résultats et outputs

Chaque chunk peut être exécuté individuellement grâce à la flèche verte.
Les options associées à chaque chunks sont disponible avec la roue crantée.

Modifier le document (en plusieurs commits)
- ajoutez un chunk knitr::kable(head(iris)) pour visualiser un table
- ajoutez un chunk plot(cars) pour un plot
- ajoutez un chunk bash pwd par exemple
- ajoutez des commentaires mis en forme avec markdown
- ajoutez une formule tel que $\Delta = b^2 - 4ac$
Lorsque vous êtes satisfait de votre rapport, générez la version HTML en cliquant sur Knit. Commitez, pushez, …
Visualisez les modifications côté GitHub
Pour rentre une page HTML visualisable avec GitHub Pages
- Dans les options du repo, dans le chapitre “GitHub Pages”, activer la source correspondant à la branch main (ou master suivant votre configuration)
- Le README.md est interprété et disponible à l’adresse https://[user].github.io/
- La page HTML générée est disponible à l’adresse https://[user].github.io/[repo]/[page].html

Si vous utilisez GitLab, pour afficher directement les html :

Créer un fichier .gitlab-ci.yml

# This file is a template, and might need editing before it works on your project.
# Full project: https://gitlab.com/pages/plain-html

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - rm -rf public
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Le contenu du dépôt est copié dans le dossier public/ et exposé suivant vos paramètres de confidentialité
L’URL est disponible dans l’onglet Pages

Votre rapport est disponible, versionné et partageable !

Suivant l’interlocuteur, partagez le .Rmd ou le .html

4 Intégration Continue

4.1 Pour GitHub

Pour compiler a chaque modification les RMarkdown dans un environnement on utilise les GitHub Actions. Il existe de nombre templates disponibles, notament ceux porposé par usethis (liste d’exemples)
Pour aujourd’hui, créez le fichier .github/workflows/render-rmarkdown.yaml tel que

on:
  push:
    paths: ['**.Rmd']

name: render-rmarkdown

jobs:
  render-rmarkdown:
    runs-on: ubuntu-latest
    container:
      image: rocker/verse:4
    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Install packages
        run: |
          Rscript -e 'install.packages("rmarkdown")'
      
      - name: Render Rmarkdown files and Commit Results
        run: |
          Rscript -e "purrr::map(fs::dir_ls(regexp = '.Rmd$'), rmarkdown::render)"
          git config --global --add safe.directory /__w/${{ github.event.repository.name }}/${{ github.event.repository.name }}
          git config --global user.name "$GITHUB_ACTOR"
          git config --global user.email "$GITHUB_ACTOR@users.noreply.github.com"
          git add *.html
          git commit -m 'Re-build Rmarkdown files' || echo "No changes to commit"
          git push origin || echo "No changes to commit"

Sur GitHub, autorisez les modifications (commit) par le workflow : Settings > Actions > General > Workflow permissions > Read and write permissions
Poussez les modifications
Sur GitHub, explorez l’onglet Actions …

Pour une meilleur gestion des packages utilisés dans votre projet, il est conseillé d’utiliser {renv} (The renv package helps you create reproducible environments for your R projects. Use renv to make your R projects more isolated, portable and reproducible.)

Pour aller plus loin

Voir aussi

4.2 Pour GitLab

Le pipeline est défini dans .gitlab-ci.yml
On utilise une image Docker R de départ
On déporte le knit sur les runners de la forge.
Pour chaque modification poussée sur le dépôt, GitLab CI/CD exécute le pipeline qui publie immédiatement les modifications sur le site.

Exemple :

image: rocker/verse:4

before_script:
  - R -e "install.packages('rmarkdown')"

pages:
  stage: deploy
  script:
    - Rscript -e "purrr::map(fs::dir_ls(regexp = '.Rmd$'), rmarkdown::render)"
    - mkdir .public
    - cp -r ./* .public
    - rm -rf public
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

On retrouve les étapes pas à pas dans Paramètres > Pages

A chaque commit les notebooks sont régénérés pour assurer une cohérence des résultats.
On peut ajouter des tests, des builds, des déploiements, etc …

4.3 Quarto

Quarto commence à remplacer rmarkdown pour générer des documents computations sans dépendre explicitement de R. Par soucis de temps, nous ne détaillerons pas son usage ici. Pour aller plus loin, voir:

5 Complément : se connecter en ssh au cluster `@front` grace aux clés ssh

Comme l’on a utiliser les clés SSH pour se connecter à GitHub depuis front, il est possible de se connecter à front depuis votre ordinateur.

On crée une nouvelle paire de clés

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

On l’envoie de manière sécurisé en rentrant pour une dernière fois sa phrase de passe.

ssh-copy-id -i id_rsa.pub <login>@front.migale.inrae.fr

Maintenant on peut se connecter plus facilement

ssh <login>@front.migale.inrae.fr

La liste des clés autorisées est regroupé dans ~/.ssh/authorized_keys
Le bonus du bonus : utiliser des alias. On peut renseigner dans le fichier .ssh/config des paramètres de connexion tel le login et l’adresse du serveur. Voici un exemple de .ssh/config :

Host *
    ForwardAgent yes
    ForwardX11 yes
    ForwardX11Trusted yes
    ForwardX11Timeout 8h
    ServerAliveInterval 120

Host front
    HostName front.migale.inrae.fr
    User <login>
    
Host ifb
    HostName core.cluster.france-bioinformatique.fr
    User <login>

En combinant ceci et les clés SSH, on peut se connecter avec :

ssh front

Vous pouvez mutualiser votre paire de clé depuis plusieurs terminaux mais la clé privée est extrêmement confidentielle et il faut être très vigilent aux fuites et pertes.

6 References

Réutilisation

CC BY-SA 4.0

A work by Migale Bioinformatics Facility
Université Paris-Saclay, INRAE, MaIAGE, 78350, Jouy-en-Josas, France
Université Paris-Saclay, INRAE, BioinfOmics, MIGALE bioinformatics facility, 78350, Jouy-en-Josas, France