GitLab Runner : installation, configuration et bonnes pratiques pour vos pipelines CI/CD

Derrière chaque pipeline CI/CD réussi se cache un acteur discret mais indispensable : GitLab Runner. C’est lui qui exécute les jobs définis dans vos fichiers .gitlab-ci.yml et permet de lancer des tests, de construire une application ou de déployer du code.

Sans runner, vos pipelines restent à l’état de promesse. Avec lui, ils deviennent concrets et reproductibles. Dans cet article, nous allons expliquer ce qu’est GitLab Runner, comment l’installer et le configurer, puis partager des bonnes pratiques pour en tirer le meilleur parti.

Qu’est-ce que GitLab Runner ?

GitLab Runner est une application open source écrite en Go, qui exécute les jobs de vos pipelines CI/CD. Lorsqu’un développeur effectue un push du code, GitLab déclenche un pipeline et distribue les jobs aux runners disponibles. Ceux-ci s’exécutent puis renvoient leurs résultats (logs, artefacts, statut) à GitLab.

Un pipeline étant une suite automatisée de jobs (compilation, test, déploiement), le runner est l’agent chargé de les exécuter sur une machine donnée. L’executor du runner définit quant à lui l’environnement dans lequel les jobs s'exécutent : Docker, Shell, Kubernetes, etc.

→ Essayez GitLab Ultimate et GitLab Duo Enterprise gratuitement.

Quels sont les types de runners disponibles dans GitLab CI/CD ?

GitLab Runner propose les types de runners suivants, disponibles en fonction des personnes auxquelles vous souhaitez donner accès :

• Les runners d’instance : disponibles pour tous les groupes et projets d'une instance GitLab.
• Les runners de groupe : disponibles pour tous les projets et sous-groupes d'un groupe.
• Les runners de projets : associés à des projets spécifiques. En général, les runners de projet sont utilisés par un seul projet à la fois.

Ces runners peuvent être hébergés de deux manières différentes :

• Les runners hébergés : gérés par GitLab et disponibles sur GitLab.com, sans installation requise. Bien qu'ils permettent de démarrer rapidement, leurs possibilités de configuration restent restreintes.
• Les runners auto-hébergés : installés, configurés et administrés par vos soins sur vos serveurs, machines virtuelles ou clusters. Ils offrent un contrôle total et s’adaptent aux environnements spécifiques.

Quels sont les executors supportés par GitLab Runner ?

Lors de l’installation d’un GitLab Runner, vous devez choisir un executor, c’est-à-dire l’environnement dans lequel vos jobs seront exécutés. Le choix de l’executor a un impact direct sur la sécurité, la performance et la flexibilité de vos pipelines.

Voici les executors les plus utilisés :

• Docker : il exécute chaque job dans un conteneur isolé. Il est rapide, flexible et recommandé pour la majorité des projets.
• Shell : il exécute directement les jobs sur la machine hôte. Il est simple, mais sans isolation.
• Kubernetes : il exécute les jobs dans des pods Kubernetes, avec une scalabilité native.
• VirtualBox / Parallels : il exécute des jobs dans des environnements spécifiques comme macOS.

Le choix dépend de vos besoins. Pour la plupart des projets, Docker est la meilleure option. Pour en savoir plus sur les executors, consultez notre documentation.

Comment installer GitLab Runner ?

L’installation de GitLab Runner dépend de votre système d’exploitation et de votre environnement cible. Voici les scénarios les plus courants.

Installation sur Linux (Debian/Ubuntu)

Linux est le système le plus fréquent pour héberger des runners auto-hébergés, notamment côté serveurs. Son installation peut se faire de deux manières :

• Via le dépôt officiel de GitLab
• Via un paquet .deb ou .rpm
• Via un fichier binaire

L’exemple ci-dessous, illustre l’installation d’un paquet provenant du dépôt GitLab avec Debian/Ubuntu :

1. Ajoutez le dépôt officiel de GitLab :

      curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

    

2. Installez la dernière version de GitLab Runner ou passez à l'étape suivante pour installer une version spécifique :

      sudo apt install gitlab-runner

    

3. Pour installer une version spécifique de GitLab Runner :

      apt-cache madison gitlab-runner

sudo apt install gitlab-runner=17.7.1-1 gitlab-runner-helper-images=17.7.1-1

    

Si vous essayez d'installer une version spécifique de gitlab-runner sans installer la même version de gitlab-runner-helper-images, vous risquez de rencontrer l'erreur suivante :

      sudo apt install gitlab-runner=17.7.1-1

...

The following packages have unmet dependencies:
 gitlab-runner : Depends: gitlab-runner-helper-images (= 17.7.1-1) but 17.8.3-1 is to be installed
E: Unable to correct problems, you have held broken packages.

    

4. Enregistrez le runner.

      sudo gitlab-runner register

    

Installation sur Windows et macOS

Si vos projets ont des exigences particulières en matière de compilation, vous pouvez également installer GitLab Runner sur Windows ou macOS en suivant les instructions suivantes :

• Installer GitLab Runner sur Windows.
• Installer GitLab Runner sur MacOS.

Installation avec Docker

Docker est souvent la méthode la plus simple et la plus rapide pour mettre en place un GitLab Runner. Elle permet d’exécuter un GitLab runner dans un conteneur Docker sans installation complexe, tout en bénéficiant d’un environnement isolé et facile à reproduire.

C’est une solution idéale pour les tests rapides, les environnements de développement temporaires, ou encore pour les équipes qui travaillent déjà largement avec des conteneurs.

1. Lancez le conteneur

      docker run -d --name gitlab-runner --restart always \ 
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \ 
  gitlab/gitlab-runner:latest

    

2. Enregistrez le runner

      docker exec -it gitlab-runner gitlab-runner register

    

Installation avec Kubernetes

L'installation du GitLab Runner avec Kubernetes se fait à l’aide du Helm Chart de GitLab. Ce mode d’installation est le moyen officiel de déployer une instance GitLab Runner dans votre cluster Kubernetes.

Voici comment installer GitLab Runner à partir du Helm Chart de GitLab :

1. Ajoutez le dépôt GitLab Helm :

      helm repo add gitlab https://charts.gitlab.io

    

2. Vérifiez les versions de GitLab Runner auxquelles vous avez accès :

      helm search repo -l gitlab/gitlab-runner

    

3. Si vous ne parvenez pas à accéder aux dernières versions de GitLab Runner, mettez à jour le graphique à l'aide de cette commande :

      helm repo update gitlab

    

4. Après avoir configuré le GitLab Runner dans votre fichier values.yaml, exécutez cette commande en modifiant les paramètres si nécessaire :

      # For Helm 3

helm install --namespace <NAMESPACE> gitlab-runner \ 
  -f <CONFIG_VALUES_FILE> \ 
  gitlab/gitlab-runner

    

• <NAMESPACE> : l'espace de nommage Kubernetes où vous souhaitez installer GitLab Runner.
• <CONFIG_VALUES_FILE> : le chemin d’accès vers le fichier de valeurs contenant votre configuration personnalisée. Pour le créer, consultez notre documentation.
• Pour installer une version spécifique du Helm Chart GitLab Runner, ajoutez --version <RUNNER_HELM_CHART_VERSION> à votre commande helm install. Vous pouvez installer n'importe quelle version du Helm Chart, mais les fichiers values.yml plus récents peuvent être incompatibles avec les versions plus anciennes.

Pour en savoir plus sur comment installer un GitLab Runner avec Kubernetes, consultez notre documentation.

Consultez notre FAQ pour en savoir plus sur l’installation d’un GitLab Runner.

Comment enregistrer un GitLab Runner ?

Une fois installé, GitLab Runner doit être enregistré pour qu’il puisse récupérer les jobs depuis l’instance GitLab. Cette étape consiste à connecter votre runner installé à une ou plusieurs instances GitLab.

Il existe plusieurs manières d’enregistrer un GitLab Runner. Dans cet article, nous nous concentrerons sur l’enregistrement d’un runner via un token d’authentification.

Prérequis

• Obtenez un token d'authentification de runner. Vous pouvez soit :
• Créer un runner d'instance, de groupe ou de projet. Pour les instructions, consultez notre documentation sur la gestion des runners.
• Localiser le token d'authentification du runner dans le fichier config.toml. Les tokens d'authentification de runner ont le préfixe glrt-.

Une fois le runner enregistré, la configuration est sauvegardée dans le fichier config.toml, qui est le fichier de configuration principal de GitLab Runner et contient tous les paramètres nécessaires au fonctionnement du runner et à l'exécution des jobs CI/CD. Ce fichier peut être modifié à tout moment : chaque changement est pris en compte dès le prochain job, sans redémarrage nécessaire du service.

Pour enregistrer le runner avec un jeton d'authentification du runner vous devez :

1. Exécutez la commande d'enregistrement en fonction de votre mode d’installation,
2. Saisissez l’URL de votre instance GitLab (GitLab.com ou GitLab Self-Managed),
3. Renseignez le token d'authentification du runner,
4. Ajoutez une description pour le runner et les tags de job,
5. Renseignez l’executor choisi (Docker, Shell, Kubernetes, etc.).

Pour enregistrer plusieurs runners sur la même machine hôte, chacun avec une configuration différente, répétez la commande register et pour enregistrer la même configuration sur plusieurs machines hôtes, utilisez le même token d'authentification de runner pour chaque enregistrement de runner.

Vous pouvez également utiliser le mode non-interactif pour utiliser des arguments supplémentaires afin d'enregistrer le runner.

Prenons un exemple avec Linux :

      sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

    

Tester le bon fonctionnement et commencer à utiliser votre runner

Avant d’intégrer le runner à vos workflows, vérifiez qu’il fonctionne correctement :

1. Vérifiez dans l’interface de GitLab

a. Dans votre projet, accédez à Paramètres > CI/CD > Runners.

b. Vérifiez que votre runner est actif et fonctionnel.

2. Vérifiez en ligne de commande selon votre mode d’installation sélectionné.
3. Testez avec un pipeline simple en créant un fichier .gitlab-ci.yml :

      
test-runner: 
  stage: test 
  script: 
   - echo "Hello GitLab Runner" 
   - hostname 
   - date 
tags: 
   - my-tags # ⚠️ Replace with YOUR runner's tags

    

Bonnes pratiques pour sécuriser et optimiser GitLab Runner

Un GitLab Runner mal configuré peut entraîner des lenteurs ou des failles de sécurité. Voici les bonnes pratiques pour en tirer le meilleur parti dans vos pipelines CI/CD.

Sécurité des runners

• Privilégier des environnements isolés : utilisez de préférence les executors Docker ou Kubernetes, qui offrent une séparation claire entre les jobs, plutôt que le mode Shell qui exécute les commandes directement sur la machine hôte.
• Limiter les permissions : évitez d’accorder des droits administrateurs aux runners si ce n’est pas nécessaire. Configurez-les avec le minimum d’autorisations pour réduire la surface d’attaque.
• Contrôler l’accès par tags : attribuez des tags spécifiques aux runners afin qu’ils n’exécutent que certains jobs. Cela permet d’éviter qu’un job non prévu tourne sur un runner sensible.

Performance et rapidité des pipelines

• Utiliser des images légères : pour les executors Docker, sélectionnez des images adaptées et optimisées (par exemple alpine plutôt que ubuntu si cela suffit) afin de réduire le temps de démarrage des conteneurs.
• Configurer le cache : tirez parti du cache de GitLab pour réutiliser des dépendances ou des fichiers générés entre plusieurs pipelines. Cela diminue le temps d’exécution global.
• Exécuter parallèlement : divisez vos jobs en plusieurs étapes qui peuvent tourner en parallèle, afin de réduire le temps total d’un pipeline.

Maintenance et fiabilité

• Mettre à jour régulièrement les runners : chaque version apporte des correctifs et de nouvelles fonctionnalités. Garder vos runners synchronisés avec la version de GitLab est un gage de compatibilité et de stabilité.
• Superviser vos runners : utilisez les métriques intégrées (par exemple via Prometheus) pour suivre la charge, le temps d’exécution des jobs ou l’utilisation des ressources. Cela aide à anticiper les goulots d’étranglement.
• Prévoir la redondance : dans un environnement critique, installez plusieurs runners pour répartir la charge et éviter qu’un incident n'interrompt vos pipelines.

Aller plus loin avec GitLab CI/CD

GitLab Runner prend toute sa valeur lorsqu’il est intégré aux pipelines CI/CD, aux tests de sécurité et à l’automatisation complète de GitLab. Consultez également notre documentation pour découvrir nos bonnes pratiques de gestion d'une flotte de runners GitLab dans un modèle de service partagé.

→ Essayez GitLab Ultimate et GitLab Duo Enterprise gratuitement.