Gitlab CI/CD

Introduction

La forge du département informatique propose de nombreux runners permettant d'effectuer des jobs d'intégration continue et déploiement continu.

Pour créer une CI/CD dans votre projet il suffit de créer un fichier .gitlab-ci.yml. L'objectif de cette page n'est pas d'écrire un tutoriel sur Gitlab CI/CD mais de vous rediriger vers les bonnes ressources.

Le pipeline

Le pipeline est votre processus de CI/CD, il est produit suite à un évènement (manuel ou un push). Il s'agit d'un regroupement d'actions au sein de jobs réalisés dans un ordre déterminé par des stages. Tous les jobs s'exécutent dans un runner mis à votre disposition par la forge!

Les jobs sont exécutés en parallèle dans un stage. Si tous les jobs finissent avec le statut succeed, le pipeline passe au prochain stage. Sinon, c'est un échec et il sera nécessaire de corriger les erreurs dans votre code!

Ci-dessous vous trouverez l'exemple officiel de Gitlab:

build-job:
  stage: build
  script:
    - echo "Hello, $GITLAB_USER_LOGIN!"

test-job1:
  stage: test
  script:
    - echo "This job tests something"

test-job2:
  stage: test
  script:
    - echo "This job tests something, but takes more time than test-job1."
    - echo "After the echo commands complete, it runs the sleep command for 20 seconds"
    - echo "which simulates a test that runs 20 seconds longer than test-job1"
    - sleep 20

deploy-prod:
  stage: deploy
  script:
    - echo "This job deploys something from the $CI_COMMIT_BRANCH branch."
  environment: production

Le code va produire un pipeline avec quatre jobs dont deux seront exécutés en même temps pendant la phase des tests. Il est possible de suivre l'avancement en vous rendant sur la forge, puis une fois dans votre projet, vous allez dans Build(1) > Pipelines(2). Si tout fonctionne correctement, il y aura l'image suivante, où vous pourrez choisir deux actions:

Cliquer sur le status(image "Un pipeline") du pilepine pour voir l'avancement général de vos jobs. Vous trouverez ci-dessous les valeurs possibles des statuts les plus communs:

running: le pipeline est toujours en cours d'exécution et aucune erreur pour le moment.
failed: au moins un job a retourné une erreur.
success: le pipeline est terminé et l'intégralité des jobs se sont terminés correctement.
pending: votre pipeline est en attente qu'un runner le prenne en charge.

Cliquer sur un job(image "Shell web d'un job") pour voir son déroulement au sein d'un shell web, les éventuels messages que vous avez mis dans le script ou le message d'erreur retourné si le job est failed!

pipelines-multiples-stages-and-status — Un pipeline

Les mots-clefs du fichier gitlab-ci.yml

Il existe une documentation dédiée sur le sujet des mots-clefs du fichier gitlab-ci.yml , ici nous allons décrire les essentiels pour débuter.

Mots-clefs de niveau global / niveau 0 du fichier YAML

Mot-clef	Description
Le nom du job	Le nom du job est un texte libre permettant d'identifier le job. Il sera affiché dans le pipeline et le nom remontera en cas d'erreur. Un nom pertinent permettra de cibler directement la section de votre fichier à modifier en cas d'erreur.
stages	Il permet d'ajouter des valeurs aux stages définis par défaut
include	Pour inclure d'autres fichiers au processus de CI/CD. Le seul objectif étant de simplifier la lisibilité du code si votre projet devient important.
default	Pour définir des valeurs par défaut entre les jobs, cela évite les instructions redondantes dans le fichier.

Mots-clefs dans un job

Mot-clef	Description
stage	Pour définir à quel moment le job sera effectué. Par défaut Gitlab propose 5 stages qui sont réalisés dans l'ordre suivant: .pre > build > test > deploy > .post
image	Pour définir l'image utilisée pour réaliser les actions de vos scripts. Il est possible d'utiliser toutes les images disponibles sur internet ou vos propres images!
script	Il s'agit d'une liste YAML pour définir vos actions, un peu comme un script bash. Vous pouvez lancer vos tests, votre compilation, votre déploiement...
rules	Très pratique pour conditionner vos jobs. Il est par exemple possible de déployer votre application en fonctionne de l'environnent ou de réaliser un déploiement uniquement si un tag de version. Les possibilités sont décrites ici.

Déployer mon code avec SSH

Il existe une documentation dédiée pour déployer son projet en production sur une machine virtuelle avec SSH . Mais vous trouverez ci-dessous un tutoriel détaillé.

Il est possible de réaliser des processus bien plus évolués que cet exemple, mais comme il a été dit au début: l'objectif ici est de donner les premiers pointeurs pour se lancer.

Pour déployer votre code sur une machine. Il est conseillé de créer un utilisateur dédié sur la machine avec sa propre clef SSH. Vous pouvez uniquement modifier la variable de USER_DEPLOY pour la faire correspondre à l'utilisateur de votre choix:

USER_DEPLOY=demo
sudo adduser --disabled-password --gecos "" $USER_DEPLOY
sudo -u $USER_DEPLOY ssh-keygen -t rsa -b 4096 -f /home/$USER_DEPLOY/.ssh/id_rsa -N ""
sudo -u $USER_DEPLOY sh -c 'cat /home/$1/.ssh/id_rsa.pub | tee -a /home/$1/.ssh/authorized_keys' _ "$USER_DEPLOY"

La prochaine étape est de récuperer la clef privée:

sudo -u $USER_DEPLOY cat /home/$USER_DEPLOY/.ssh/id_rsa

Vous pouvez maintenant donner le contenu de la clef SSH à la forge Gitlab afin que les runners puissent se connecter à votre VM. Vous devez donc vous rendre dans Settings(1) > CI/CD(2) > Cliquer sur expand dans Variables(3).

Puis il suffit d'ajouter une variable(1) avec le nom de votre choix, ça sera le nom à utiliser dans votre fichier .gitlab-ci.yml. Ici, SSH_PRIVATE_KEY(2) sera choisi comme nom de variable. Puis de passer la valeur de votre variable: la fameuse clef privée permettant la connexion à votre VM(3). Puis de valider l'ajout (4).

Il est aussi possible de cocher Mask Variable pour réduire le risque de diffuser le contenu. Mais aussi de définir un environnement dans lequel la variable sera accessible, idéal, si on veut faire varier le déploiement en fonction des avancées du projet.

Pour finir il suffit de modifier votre fichier .gitlab-ci.yml pour ajouter un stage de déploiement. Ici, on prendra un exemple simple pour un site internet, mais il faut bien évidemment adapter cette étape selon votre application.

deploy_staging:
  stage: deploy
  environment:
    name: production

 script:
    - apt-get update -qq
    # Setup SSH deploy keys
    - 'which ssh-agent || ( apt-get install -qq openssh-client )'
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
    - ssh  demo@ipmachinevirtuelle "cd nomduprojet && git pull && exit"

Dépôts témoins CI/CD

Vous trouverez ci-dessous la liste des dépôts témoins CI/CD pour vérifier la bonne intégration de votre solution sur les runners de la forge.

Maven

Vous trouverez ci-dessous des liens vers des ressources importantes de la documentation officielle: