GitLab - Utiliser une clé SSH pour se connecter à un repo privé

Dans cet article, nous allons voir comment utiliser une clé SSH privée dans une CI GitLab.

Le besoin : quand ma CI tourne, le runner GitLab doit pouvoir se connecter à mon environnement GitLab auto-hébergé (et privé). Car il devra en récupérer des projets privés. Pensez à un projet PHP par exemple : dans mon composer.json, je référence des dépendances hébergées sur mon serveur GitLab. Ou idem pour un projet JavaScript et son fichier package.json.

Autre exemple : ma CI va produire des fichiers (comme un .pdf) en convertissant des documents Markdown en une vraie documentation. À la fin de cette conversion, le PDF doit être poussé dans le repository.

Mon besoin est donc le suivant : je dois partager ma clé SSH avec le runner GitLab.

Deux articles frères sur la même CI : GitLab - Utiliser des images Docker privées, qui résout le même problème d'authentification pour une image privée plutôt que pour un repository privé, et GitLab - Exécuter Docker-out-of-Docker dans votre CI.

Voici le résultat une fois la variable CI en place : le job clone le repo privé via SSH au lieu d'échouer avec une erreur de permission.

Pourquoi ça fonctionne​

• La clé privée ne touche jamais votre .gitlab-ci.yml ni votre repo : elle vit sous forme de variable CI/CD masquée, encodée en base64, et n'est décodée dans un fichier qu'à l'intérieur du job en cours d'exécution.
• Une seule variable peut être limitée à un repo unique, à un groupe GitLab entier ou à toute l'instance : vous la configurez une fois et la réutilisez partout où vous avez besoin du même accès privé.

D'abord, il me faut une clé SSH​

Pour l'histoire complète, lisez mon article SSH - Lancer un terminal sur votre session sans avoir à vous authentifier.

Je vais créer une clé privée en exécutant ssh-keygen -t ed25519 -C "christophe@my_self_hosted_gitlab" -f ~/.ssh/id_ed25519_my_self_hosted_gitlab.

Cette commande va créer le fichier ~/.ssh/id_ed25519_my_self_hosted_gitlab. C'est ma clé privée et c'est celle dont j'aurai besoin à l'étape suivante.

Ensuite, je vais l'encoder pour plus de sécurité​

En exécutant cat ~/.ssh/id_ed25519_my_self_hosted_gitlab | base64 -w 0, je vais encoder en base64 ma clé privée sous la forme d'une très longue chaîne de caractères alphanumériques.

Je dois copier cette longue chaîne dans le presse-papiers.

Troisièmement, je dois créer une variable CI SSH_PRIVATE_KEY​

Ici, j'ai plusieurs possibilités :

• j'utilise la variable pour un seul repo ;
• j'utilise la variable pour tous les repositories d'un groupe donné (un groupe GitLab est comme un dossier contenant plusieurs repos) ;
• j'utilise la variable pour tous les repositories stockés sur mon instance GitLab.

En allant dans mon repository, je dois cliquer sur CI/CD Settings, déplier la zone Variables pour pouvoir ajouter une nouvelle variable.

Le nom de la variable doit être SSH_PRIVATE_KEY et je choisis Masked (ou Masked and hidden) pour la visibilité. Pour la valeur, je colle la chaîne encodée en base64 que je viens de copier dans le presse-papiers.

Je finalise la création de la variable en cliquant sur le bouton Add variable présent en bas du panneau.

Enfin, je dois adapter mon fichier .gitlab-ci.yml​

Comme exemple, je vais réutiliser celui fourni par GitLab : https://gitlab.com/gitlab-examples/ssh-private-key/-/blob/main/.gitlab-ci.yml

using_ssh_key:
  image: ubuntu
  before_script:
    - |
      apt-get update -y && apt-get install openssh-client git -y
      eval $(ssh-agent -s)?
      mkdir -p ~/.ssh && chmod 700 ~/.ssh?
    - |
      echo "$SSH_PRIVATE_KEY" | base64 -d > ~/.ssh/id_ed25519?
      cat ~/.ssh/id_ed25519
      chmod 400 ~/.ssh/id_ed25519?
    - |
      ssh-keyscan my_self_hosted_gitlab >> ~/.ssh/known_hosts?
      chmod 644 ~/.ssh/known_hosts
  script:
    - | # try to connect to my GitLab server
      ssh -T git@my_self_hosted_gitlab
    # - | # try to clone a private repo
    #   git clone git@my_self_hosted_gitlab:my_repo.git

Conclusion​

Une paire de clés, une variable CI/CD masquée encodée en base64 et quelques lignes dans .gitlab-ci.yml : c'est tout ce qu'il faut pour que votre CI clone un repository privé via SSH, sans jamais committer un secret dans votre code. Voyez GitLab - Utiliser des images Docker privées pour le même problème d'authentification appliqué à une image Docker privée plutôt qu'à un repository privé.