Artefacts et cache GitLab CI/CD

Vos jobs s’exécutent sur des runners, mais votre npm install prend 3 minutes à chaque fois ? Le problème : les dépendances sont retéléchargées à chaque job. La solution : le cache pour réutiliser les dépendances, et les artefacts pour passer des fichiers entre jobs. Ce guide vous montre comment optimiser vos pipelines.

En 30 secondes

• Artefacts = fichiers passés entre jobs du même pipeline (build → test)
• Cache = fichiers réutilisés entre pipelines différents (dependencies)
• Règle d’or : cache pour les dépendances, artefacts pour les résultats de build

Ce que vous allez apprendre

À la fin de ce module, vous saurez :

• Différencier artefacts et cache : deux mécanismes complémentaires
• Configurer les artefacts : passer des fichiers entre jobs (dist/, coverage/)
• Configurer le cache : réutiliser node_modules/, .venv/ entre pipelines
• Choisir la bonne clé de cache : invalider automatiquement quand les dépendances changent
• Optimiser les performances : réduire le temps de pipeline de 50-90%
• Dépanner : diagnostiquer les problèmes de cache et d’artefacts

Prérequis

Avant de continuer, assurez-vous de maîtriser :

• Écrire un fichier .gitlab-ci.yml
• Runners GitLab

Artefacts vs Cache : quelle différence ?

Aspect	Artefacts	Cache
But	Passer des fichiers entre jobs	Réutiliser entre pipelines
Portée	Jobs du même pipeline	Tous les pipelines (si cache partagé)
Durée de vie	Configurable (défaut variable selon instance)	Jusqu’à invalidation de la clé
Fiabilité	Garantie (stocké sur GitLab)	Best-effort (peut être purgé)
Téléchargeable	Oui, dans l’interface	Non
Exemple	dist/, coverage/	.npm/, .cache/pip

Glissez pour voir

Prérequis pour le cache multi-pipelines

Le cache n’est réutilisé entre pipelines que si :

• Runner unique : le job retombe sur le même runner (disque local)
• Cache distribué : S3, GCS ou Azure Blob configuré côté runner (obligatoire pour autoscaling/Kubernetes)

GitLab.com utilise un cache distribué. En self-managed avec plusieurs runners, configurez un backend partagé sinon le cache sera “hit or miss”. Documentation cache distribué.

Artefacts : passer des fichiers entre jobs

Les artefacts permettent de conserver des fichiers d’un job et de les passer aux jobs suivants.

Configuration de base

build:
  stage: build
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

test:
  stage: test
  script:
    - npm test dist/    # dist/ est automatiquement disponible

Options des artefacts

artifacts:
  paths:
    - dist/
    - coverage/
  exclude:
    - "**/*.map"          # Exclure les source maps
  expire_in: 1 week       # Durée de conservation
  when: always            # Même si le job échoue
  name: "build-$CI_COMMIT_SHA"  # Nom du fichier zip

Exception : dernier pipeline réussi

GitLab conserve automatiquement les artefacts du dernier pipeline réussi pour chaque branche, indépendamment de expire_in. C’est utile pour les déploiements, mais peut consommer du stockage. Désactivable dans Settings > CI/CD > Artifacts.

Valeurs de when :

Valeur	Comportement
on_success	Uniquement si le job réussit (défaut)
on_failure	Uniquement si le job échoue
always	Dans tous les cas

Glissez pour voir

Télécharger les artefacts

Les artefacts sont téléchargeables depuis l’interface GitLab :

1. CI/CD > Jobs → cliquez sur un job
2. Bouton Download artifacts (à droite)
3. Ou dans CI/CD > Artifacts pour voir tous les artefacts

Rapports de test

GitLab comprend certains formats de rapport pour les afficher dans l’interface :

test:
  script:
    - npm test -- --coverage --reporters=jest-junit
  artifacts:
    reports:
      junit: junit.xml          # Résultats de tests
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura.xml

Cela affiche les tests échoués directement dans la merge request !

Cache : réutiliser entre pipelines

Le cache conserve des fichiers entre les pipelines pour éviter de retélécharger les dépendances.

Configuration de base

build:
  cache:
    paths:
      - node_modules/
  script:
    - npm ci
    - npm run build

Clé de cache

La clé de cache détermine quand le cache est réutilisé ou recréé :

cache:
  key: $CI_COMMIT_REF_SLUG    # Une clé par branche
  paths:
    - node_modules/

Clés courantes :

Clé	Comportement
default	Cache global, partagé par tout
$CI_COMMIT_REF_SLUG	Un cache par branche
$CI_JOB_NAME	Un cache par job
Fichier hash (voir ci-dessous)	Invalidé quand le fichier change

Glissez pour voir

Clé basée sur un fichier

Pour invalider le cache quand les dépendances changent :

cache:
  key:
    files:
      - package-lock.json    # Nouvelle clé si le lock change
  paths:
    - node_modules/

Si package-lock.json change, le cache est recréé automatiquement.

Politique de cache

Contrôlez quand le cache est lu ou écrit :

# Job qui lit ET écrit le cache (défaut)
install:
  cache:
    policy: pull-push
    paths:
      - node_modules/
  script:
    - npm ci

# Job qui lit seulement (plus rapide)
test:
  cache:
    policy: pull
    paths:
      - node_modules/
  script:
    - npm test

Politique	Lecture	Écriture	Cas d’usage
pull-push	✅	✅	Job qui installe (défaut)
pull	✅	❌	Jobs qui utilisent seulement
push	❌	✅	Régénérer le cache

Glissez pour voir

Exemples par langage

Node.js

npm ci supprime et recrée node_modules/ à chaque exécution. Le gain vient du cache npm (tarballs téléchargés), pas de node_modules/ :

variables:
  NPM_CONFIG_CACHE: "$CI_PROJECT_DIR/.npm"

default:
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/              # Cache des tarballs, pas node_modules
    policy: pull-push

install:
  stage: install
  script:
    - npm ci --prefer-offline   # Utilise le cache local si possible
  cache:
    policy: pull-push

build:
  stage: build
  script:
    - npm ci --prefer-offline
    - npm run build
  cache:
    policy: pull
  artifacts:
    paths:
      - dist/

test:
  stage: test
  script:
    - npm ci --prefer-offline
    - npm test
  cache:
    policy: pull

Python

Cacher un venv complet peut casser (image différente, version Python, dépendances natives). Plus robuste : cache pip (téléchargements) + artefact venv (même pipeline) :

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

default:
  cache:
    key:
      files:
        - requirements.txt
    paths:
      - .cache/pip/       # Cache des téléchargements pip
    policy: pull-push

install:
  stage: install
  script:
    - python -m venv .venv
    - . .venv/bin/activate
    - pip install -r requirements.txt
  artifacts:
    paths:
      - .venv/            # Artefact pour les jobs suivants
    expire_in: 1 day

test:
  stage: test
  script:
    - . .venv/bin/activate
    - pytest
  # Pas besoin de cache:policy ici, le venv vient des artefacts

Maven/Java

default:
  cache:
    key:
      files:
        - pom.xml
    paths:
      - .m2/repository/

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository"

build:
  stage: build
  script:
    - mvn clean package -DskipTests
  artifacts:
    paths:
      - target/*.jar

test:
  stage: test
  script:
    - mvn test

Go

Cachez à la fois le module cache (dépendances) et le build cache (compilation) pour un gain maximal :

variables:
  GOPATH: "$CI_PROJECT_DIR/.go"
  GOMODCACHE: "$CI_PROJECT_DIR/.go/pkg/mod"
  GOCACHE: "$CI_PROJECT_DIR/.cache/go-build"

default:
  cache:
    key:
      files:
        - go.sum
    paths:
      - .go/pkg/mod/       # Modules téléchargés
      - .cache/go-build/   # Résultats de compilation
    policy: pull-push

build:
  stage: build
  script:
    - go build -o app ./...
  artifacts:
    paths:
      - app

test:
  stage: test
  script:
    - go test ./...
  cache:
    policy: pull

Stratégies d’optimisation

1. Cache les téléchargements, pas le build

# ✅ Bon : cache des téléchargements
cache:
  paths:
    - .npm/          # ou .cache/pip, .m2/repository

# ❌ Mauvais : dist/ doit être en artefact, pas en cache
cache:
  paths:
    - .npm/
    - dist/

2. Utilisez policy: pull pour les jobs qui ne modifient pas le cache

test:
  cache:
    policy: pull    # 2x plus rapide que pull-push

3. Clé basée sur le fichier de lock

cache:
  key:
    files:
      - package-lock.json    # Invalide auto si dépendances changent

4. Un job dédié à l’installation

install:
  stage: .pre              # Stage spécial, avant tous les autres
  script:
    - npm ci
  cache:
    policy: pull-push
    paths:
      - node_modules/

# Les autres jobs utilisent policy: pull

Dépannage

Problème	Cause probable	Solution
Cache jamais utilisé	Clé différente à chaque run	Vérifier la clé de cache
Cache obsolète	Lock file changé	Bonne chose ! Le cache se reconstruit
”Cache not found”	Premier run ou cache purgé	Normal, le cache se recréera
Cache OK en local, KO en autoscale	Pas de cache distribué	Configurer S3/GCS côté runner
Artefacts non trouvés	Job dans un stage différent échoué	Vérifier les dépendances entre stages
Artefacts expirés	expire_in trop court	Augmenter la durée
Artefacts jamais supprimés	Dernier pipeline réussi conservé	Désactiver dans Settings > CI/CD

Glissez pour voir

Voir les logs de cache

Dans les logs du job, cherchez :

• Checking cache for key...
• Successfully extracted cache
• Creating cache key...

À retenir

1. Artefacts = fichiers entre jobs (même pipeline), Cache = fichiers entre pipelines
2. Cache pour les téléchargements (.npm/, .cache/pip), artefacts pour les résultats (dist/, .venv/)
3. Clé basée sur le lock file pour invalider automatiquement quand les dépendances changent
4. policy: pull pour les jobs qui ne modifient pas le cache (plus rapide)
5. Cache distribué requis pour autoscaling/Kubernetes (S3, GCS, Azure Blob)
6. Le cache est best-effort — votre pipeline doit fonctionner sans

Contrôle des connaissances

Testez vos connaissances sur les artefacts et le cache GitLab CI/CD.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

10 questions

5 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Prochaines étapes

Variables et secrets Configurer les variables d'environnement et protéger les secrets.

Rules (conditions) Contrôler quand les jobs s'exécutent.

DAG et parallélisme Optimiser l'ordre d'exécution avec needs.

×

📖 Voir la documentation →