GitLab Runner: Construire des images Docker

Construisez et poussez des images Docker efficacement depuis vos pipelines GitLab CI/CD grâce aux runners Stackhero et à Docker-in-Docker

👋 Bienvenue sur la documentation de Stackhero !

Stackhero propose une solution GitLab Runner cloud simple qui facilite l'exécution de vos jobs GitLab CI/CD, de façon efficace et sans contraintes. Voici ce que vous pouvez attendre :

Minutes CI/CD illimitées : exécutez vos pipelines aussi souvent que nécessaire, sans facturation à la minute ni frais imprévus.

Plusieurs jobs simultanés : accélérez votre développement en lançant plusieurs jobs en parallèle.

L'executor Docker avec prise en charge de Docker-in-Docker : construisez et poussez facilement des images de conteneurs dans vos processus CI/CD.

Fonctionne parfaitement avec GitLab.com et les instances GitLab auto-hébergées.

Une infrastructure privée et dédiée avec un stockage NVMe/SSD rapide garantit des performances de build stables et prévisibles.

Disponible dans les régions 🇪🇺 Europe et 🇺🇸 USA pour répondre aux besoins de votre équipe.

Gagnez du temps : vous pouvez connecter votre premier GitLab Runner et lancer vos pipelines en seulement quelques minutes !

Introduction

Avec un GitLab Runner Stackhero, chaque job s'exécute dans un conteneur isolé en utilisant l'executor Docker. Vous pouvez construire vos propres images Docker directement dans votre pipeline en activant Docker-in-Docker (DinD). Cette configuration lance un démon Docker à côté de votre job, ce qui vous permet d'exécuter les commandes docker build et docker push dans votre processus CI/CD.

Chaque exécution bénéficie de minutes CI/CD illimitées : vous pouvez lancer autant de builds que nécessaire, sans vous soucier de quotas. Votre cache de build est stocké sur le disque dédié du runner, ce qui permet de réutiliser les couches précédentes lors de builds répétés. Cela réduit considérablement les temps de build et accélère vos pipelines.

Construire une image Docker avec Docker-in-Docker

Vous pouvez ajouter le fichier .gitlab-ci.yml suivant à votre dépôt. Cette configuration construit le Dockerfile situé à la racine de votre projet :

build-image:
  stage: build
  image: docker:29
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - docker info
  script:
    # Remplacez "my-image" par le nom souhaité :
    - docker build -t my-image .
    # Optionnellement, lancez un test rapide sur l'image construite :
    # - docker run --rm my-image /path/to/tests

Nous utilisons ici la version 29 de l'image Docker. Vous pouvez choisir une version plus récente si besoin. Retrouvez les tags les plus récents sur la page officielle Docker image.

Dans cette configuration, le service docker:29-dind démarre un démon Docker à côté de votre job, et DOCKER_HOST: "tcp://docker:2375" indique au CLI docker de l'utiliser. Définissez toujours DOCKER_HOST lorsque vous déclarez un service docker:dind : sans cela, le CLI se connecte silencieusement à un autre démon, ce qui peut faire passer le build même si le service est mal configuré, masquant ainsi des problèmes réels (et perturbant des outils comme Testcontainers qui dépendent du service). DOCKER_TLS_CERTDIR: "" permet une connexion sur le port interne non sécurisé 2375 du réseau du job.

En alternative plus simple, vous pouvez omettre le bloc services et les deux variables : le runner Stackhero expose aussi un démon Docker prêt à l'emploi via un socket monté, donc une simple commande docker build fonctionne sans configuration supplémentaire.

Exécuter vos tests avec Testcontainers

Testcontainers est une bibliothèque de tests, disponible pour Java, Go, Node.js, Python, .NET et d'autres langages, qui lance de vrais services sous forme de conteneurs Docker jetables pendant l'exécution de vos tests. Plutôt que de simuler une base de données ou un message broker, vos tests d'intégration dialoguent avec une véritable instance PostgreSQL, MySQL, Redis ou Kafka, créée avant les tests et supprimée juste après. Cette solution est particulièrement populaire dans les projets Java et Spring.

Testcontainers a besoin d'un démon Docker, il fonctionne donc avec exactement la même configuration Docker-in-Docker que précédemment. Aucune variable supplémentaire n'est requise :

test:
  stage: test
  # Utilisez l'image adaptée à vos tests (ici un JDK), pas forcément l'image docker :
  image: gradle:jdk21
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  script:
    - gradle test

Testcontainers lit la variable DOCKER_HOST pour localiser le démon, et réutilise le même hostname docker pour accéder aux ports exposés par les conteneurs qu'il lance. Les deux fonctionnent car l'alias docker est résolu sur le réseau du job.

Gardez DOCKER_HOST dans vos jobs Testcontainers. Sans cette variable, Testcontainers utilise le socket Docker monté par le runner, puis tente d'accéder à vos conteneurs de test via l'adresse IP de l'hôte, ce qui n'est pas accessible depuis le job. Le symptôme classique est l'échec du conteneur helper Ryuk avec Wait strategy failed. Container is removed, ou Timed out waiting for log output matching '.*Started.*'.

Pousser vers le registre de conteneurs GitLab

GitLab fournit des variables prédéfinies (CI_REGISTRY, CI_REGISTRY_USER, CI_REGISTRY_PASSWORD, CI_REGISTRY_IMAGE) pour que votre pipeline puisse s'authentifier et pousser des images vers le registre de conteneurs de votre projet en toute sécurité. Aucun secret supplémentaire n'est nécessaire.

Voici un exemple de job qui construit et pousse votre image :

build-and-push:
  stage: build
  image: docker:29
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
  script:
    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
    - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
    # Si vous êtes sur la branche par défaut, vous pouvez aussi taguer et pousser "latest" :
    - |
      if [ "$CI_COMMIT_BRANCH" = "$CI_DEFAULT_BRANCH" ]; then
        docker tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" "$CI_REGISTRY_IMAGE:latest"
        docker push "$CI_REGISTRY_IMAGE:latest"
      fi

Pour pousser vos images vers un autre registre (comme Docker Hub ou un registre privé), vous pouvez stocker les identifiants comme variables CI/CD et les utiliser avec docker login de la même manière.

Accélérer les builds répétés

Le disque de votre runner est persistant entre les pipelines, ce qui permet de réutiliser les couches d'image comme cache de build. Cela accélère considérablement les builds successifs. Voici un exemple de configuration :

build-cached:
  stage: build
  image: docker:29
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
  script:
    # Récupérez la dernière image pour initialiser le cache (si elle existe) :
    - docker pull "$CI_REGISTRY_IMAGE:latest" || true
    - docker build --cache-from "$CI_REGISTRY_IMAGE:latest" -t "$CI_REGISTRY_IMAGE:latest" .
    - docker push "$CI_REGISTRY_IMAGE:latest"

Cette méthode permet à vos builds de profiter du cache de couches Docker, seules les couches nouvelles ou modifiées sont reconstruites.

Exécuter des jobs en parallèle

Votre offre détermine combien de jobs peuvent s'exécuter simultanément. Les jobs d'une même étape démarrent ensemble, jusqu'à la limite de concurrence définie. Plusieurs jobs indépendants peuvent donc tourner en parallèle, et se terminent dès que le plus lent est fini, sans attendre la fin des autres.

Exemple :

stages:
  - test

unit:
  stage: test
  image: node:22
  script: npm run test:unit

integration:
  stage: test
  image: node:22
  script: npm run test:integration

e2e:
  stage: test
  image: node:22
  script: npm run test:e2e

Si vous définissez votre concurrence à 1 ou plus, les jobs unit, integration et e2e s'exécuteront en parallèle.

Pour plus de détails sur la construction d'images Docker dans les pipelines GitLab CI/CD, vous pouvez consulter la documentation officielle GitLab sur l'utilisation des builds Docker.