Artifacts vs Cache : faire le bon choix

Votre workflow CI prend 8 minutes. À chaque run, il télécharge les mêmes dépendances, reconstruit les mêmes fichiers… Pourquoi recommencer à zéro alors que rien n'a changé ?

GitHub Actions propose deux mécanismes pour éviter ce gaspillage : le cache et les artifacts. Ils semblent similaires, mais ont des usages très différents. Choisir le bon mécanisme au bon moment peut diviser par deux le temps de vos workflows.

Ce que vous allez apprendre

Distinguer le cache des artifacts en une phrase
Choisir le bon mécanisme selon votre besoin
Repérer les deux erreurs classiques de confusion entre les deux
Combiner cache et artifacts dans un même workflow

La différence en une phrase

Cache et artifacts répondent à deux besoins distincts. La règle d'or tient en deux lignes, gardez-la en tête, elle tranche la plupart des cas.

Analogie : le restaurant

Imaginez un restaurant :

Le cache, c'est le garde-manger : vous y stockez des ingrédients (farine, épices, conserves) que vous réutilisez pour plusieurs services. Ils ne sont pas spécifiques à un plat.
Les artifacts, c'est le passe-plat : les plats préparés en cuisine passent par là pour arriver en salle. Ils sont spécifiques à une commande.

Dans GitHub Actions :

Le cache stocke les dépendances (node_modules, pip packages) réutilisées entre les runs
Les artifacts transportent les résultats (build, rapports) entre les jobs d'un même run

Comparaison rapide

Ce tableau met les deux mécanismes face à face sur les critères qui comptent au moment de choisir : portée, durée de vie, visibilité et cas d'usage.

Aspect	Cache	Artifacts
Objectif	Accélérer les builds répétitifs	Partager des résultats
Portée	Entre runs (workflow répété)	Entre jobs (même run)
Durée de vie	7 jours sans accès	Configurable (1-90 jours)
Visible dans l'UI	Non (interne)	Oui (téléchargeable)
Taille max	10 GB par repo (total)	10 GB par artifact
Cas d'usage	node_modules, .cache/pip	Builds, rapports, binaires

Guide de décision

Partez de votre objectif : voulez-vous accélérer une installation, ou faire circuler un résultat d'un job à l'autre ? Chacun mène à un mécanisme.

Accélérer les installations

→ Cache

Dépendances npm, pip, Maven, Gradle...

Guide complet du cache

Partager entre jobs

→ Artifacts

Builds, résultats de compilation, rapports...

Guide complet des artifacts

Situations courantes

Voici les cas concrets qui reviennent le plus souvent, classés selon le mécanisme adapté.

Quand utiliser le cache

Accélérer npm ci / pip install / mvn install
Réutiliser les dépendances entre runs
Cacher les binaires téléchargés (Terraform, kubectl...)
Accélérer les builds incrémentaux

Exemple : Vous pushez 3 commits successifs → le cache des dépendances est réutilisé pour les 3 runs.

Quand utiliser les artifacts

Partager le build entre les jobs test et deploy
Garder les rapports de tests / couverture
Télécharger les binaires depuis l'interface GitHub
Conserver les logs de debug en cas d'échec

Exemple : Un job build crée dist/, les jobs test et deploy le réutilisent sans rebuild.

Erreurs à éviter

Deux confusions reviennent sans cesse. Les reconnaître évite des workflows instables ou inutilement lents.

Cache pour partager entre jobs

# ❌ NE FONCTIONNE PAS de manière fiable
jobs:
  build:
    steps:
      - run: npm run build
      - uses: actions/cache/save@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
        with:
          path: dist/
          key: build-${{ github.sha }}

  deploy:
    needs: build
    steps:
      - uses: actions/cache/restore@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
        # Peut échouer ! Le cache n'est pas garanti

Pourquoi ? Le cache est conçu pour les runs, pas les jobs.

Solution : Utilisez un artifact.

Artifacts pour les dépendances

# ❌ Gaspillage : vous uploadez node_modules à chaque run
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
  with:
    path: node_modules/

# ✅ Utilisez le cache
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
  with:
    cache: 'npm'

Pourquoi ? Les dépendances sont réutilisables entre runs → cache.

Le pattern complet : cache + artifacts

Dans un workflow réel, vous utilisez les deux :

name: CI/CD

on:
  push:
    branches: [main]

# Aucun droit par défaut : chaque job demande le minimum
permissions: {}

jobs:
  build:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false

      # CACHE : accélérer npm ci
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci
      - run: npm run build

      # ARTIFACT : partager le build
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: dist
          path: dist/
          retention-days: 1

  deploy:
    needs: build
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
        with:
          name: dist

      - run: ./deploy.sh

Ce qui se passe :

Le cache accélère npm ci (dépendances réutilisées entre runs)
L'artifact transporte le build vers le job deploy
On ne rebuild qu'une seule fois

À retenir

Cache = entre runs

Pour les fichiers réutilisables qui accélèrent les builds répétitifs.

Artifacts = entre jobs

Pour les fichiers produits à partager ou télécharger.

Les deux sont complémentaires

Un workflow optimisé utilise le cache ET les artifacts.

Checklist :

Dépendances → Cache
Résultats de build → Artifacts
Partage entre jobs → Artifacts + needs:
Logs de debug → Artifacts avec if: failure()

Prochaines étapes

Accélérer avec le cache Clés, restore-keys et stratégies de cache avancées

Partager entre jobs (Artifacts) Upload, download et optimisation des artifacts

Déboguer les workflows Diagnostiquer un cache ou un artifact qui ne fonctionne pas