DAG et parallélisme GitLab CI/CD (needs)

Vos pipelines attendent la fin d’un stage complet alors qu’un seul job est nécessaire ? Avec needs: (DAG), un job démarre dès que ses vraies dépendances sont terminées, sans attendre tout le stage. Résultat : des pipelines souvent sensiblement plus rapides (et surtout plus parallèles).

C'est quoi un DAG ?

DAG = Directed Acyclic Graph (Graphe Orienté Acyclique). Derrière ce terme technique se cache une idée simple :

• Directed (orienté) : les dépendances ont un sens (A → B signifie “B attend A”)
• Acyclic (acyclique) : pas de boucles (A ne peut pas attendre B si B attend déjà A)

C’est comme un arbre généalogique : vos parents vous ont donné naissance, pas l’inverse. Les dépendances vont dans un seul sens.

En 30 secondes

# Sans needs : deploy attend la fin de TOUT le stage test
# Avec needs : deploy démarre dès que unit_tests finit

deploy:
  stage: deploy
  needs: ["unit_tests"]  # N'attend pas lint, ni integration_tests
  script: ./deploy.sh

Ce guide est fait pour vous si…

Pipeline trop long Les jobs attendent inutilement.

Dépendances complexes Un job dépend d'un seul autre, pas de tout un stage.

Visualiser le graphe Voir les vraies dépendances dans GitLab.

Éviter les erreurs Dépendances circulaires et autres pièges.

Ce que vous allez apprendre

À la fin de ce module, vous saurez :

• Comprendre le problème : pourquoi les stages ralentissent vos pipelines
• Utiliser needs : définir les vraies dépendances entre jobs
• Gérer les artefacts : artifacts: true/false avec needs
• Visualiser le DAG : lire le graphe de dépendances dans GitLab
• Utiliser needs: [] : démarrer un job immédiatement
• Éviter les pièges : dépendances circulaires, jobs manqués

Prérequis

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

• Concepts fondamentaux GitLab CI/CD
• Artefacts et cache

Le problème sans DAG

L’analogie du restaurant

Imaginez un restaurant où le serveur attend que tous les plats de l’entrée soient prêts avant de les servir, même si votre salade est prête depuis 10 minutes. Puis il attend que tous les plats principaux soient prêts… Votre steak refroidit pendant que le risotto de votre voisin cuit encore.

C’est exactement ce que font les pipelines GitLab par défaut : ils attendent la fin de tout un stage avant de passer au suivant.

Le comportement par défaut : stage par stage

Par défaut, GitLab exécute les pipelines stage par stage :

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script: npm run build

lint:
  stage: test
  script: npm run lint

unit_tests:
  stage: test
  script: npm test

integration_tests:
  stage: test
  script: npm run test:integration

deploy:
  stage: deploy
  script: ./deploy.sh

Décortiquons ce qui se passe :

1. Stage build : build s’exécute seul (2 minutes)
2. Stage test : lint (30s), unit_tests (3 min), integration_tests (5 min) démarrent en parallèle
3. Attente forcée : même si lint finit en 30 secondes, le stage “test” dure 5 minutes (le plus long)
4. Stage deploy : deploy démarre enfin

Problème : deploy attend que lint, unit_tests ET integration_tests soient tous terminés, même si deploy n’a besoin que de build. Si lint échoue et que vous devez le corriger, vous avez attendu 5 minutes pour rien.

Configuration avec needs

Le mot-clé needs: change la donne : au lieu de dire “attends tout le stage précédent”, vous dites “attends uniquement ces jobs spécifiques”.

Syntaxe de base

needs: prend une liste de noms de jobs. Le job actuel démarrera dès que tous les jobs listés sont terminés, peu importe leur stage.

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script: npm run build
  artifacts:
    paths:
      - dist/

lint:
  stage: test
  script: npm run lint
  needs: []                    # Pas de dépendance, démarre immédiatement

unit_tests:
  stage: test
  script: npm test
  needs: ["build"]             # Attend seulement build

integration_tests:
  stage: test
  script: npm run test:integration
  needs: ["build"]

deploy:
  stage: deploy
  script: ./deploy.sh
  needs: ["unit_tests"]        # N'attend pas lint ni integration_tests

Analysons les changements :

Job	needs	Ce qui change
lint	[] (vide)	Démarre immédiatement, en parallèle avec build
unit_tests	["build"]	Attend seulement build, pas tout le stage
integration_tests	["build"]	Pareil, attend juste build
deploy	["unit_tests"]	Démarre dès que unit_tests finit, sans attendre lint ni integration_tests

Glissez pour voir

Résultat :

Le pipeline est plus rapide car :

• lint démarre immédiatement (pas besoin d’attendre build)
• deploy n’attend pas lint ni integration_tests
• Si integration_tests prend 10 minutes mais unit_tests seulement 2, deploy démarre après 2 minutes

Options de needs

needs offre plusieurs syntaxes selon vos besoins. Commençons par la plus simple.

Liste simple

La syntaxe la plus courante : une liste de noms de jobs entre crochets.

deploy:
  needs: ["build", "test"]  # Attend que build ET test soient terminés

Le job deploy démarrera quand les deux jobs seront au vert. Si l’un échoue, deploy ne démarrera pas (comportement par défaut).

Avec contrôle des contrôle des artefacts

Quand vous utilisez needs, GitLab télécharge automatiquement les artefacts des jobs référencés (les fichiers produits par ces jobs). Mais parfois, vous voulez attendre un job sans récupérer ses fichiers.

Exemple concret : deploy attend lint (pour être sûr que le code est propre), mais n’a pas besoin des fichiers produits par lint.

deploy:
  needs:
    - job: build
      artifacts: true      # ✅ Télécharge le dossier dist/ produit par build
    - job: lint
      artifacts: false     # ⏳ Attend lint, mais ne télécharge rien

Pourquoi c’est utile ? Télécharger des artefacts prend du temps et de la bande passante. Si vous n’en avez pas besoin, artifacts: false accélère le démarrage du job.

Piège fréquent : artefacts 'disparus'

Dès qu’un job utilise needs, GitLab change de comportement : il ne télécharge plus automatiquement les artefacts des stages précédents.

Sans needs : le job reçoit les artefacts de tous les jobs des stages précédents (comportement “magique”).

Avec needs : le job ne reçoit que les artefacts des jobs listés dans needs.

Si vos fichiers “disparaissent” après avoir ajouté needs, vérifiez que vous avez bien listé le job qui les produit.

needs: [] — aucune dépendance

C’est la syntaxe la plus puissante pour accélérer vos pipelines. Un job avec needs: [] (liste vide) démarre immédiatement, sans attendre aucun autre job.

lint:
  stage: test          # Même s'il est dans le stage "test"...
  needs: []            # ...il démarre immédiatement, en parallèle avec "build" !
  script: npm run lint

Pourquoi ça marche ? Le linting analyse le code source, pas le code compilé. Il n’a pas besoin d’attendre que build produise le dossier dist/. Donc pourquoi le faire attendre ?

Jobs parfaits pour needs: []

Ces jobs n’ont généralement pas besoin des artefacts des stages précédents :

• Linting : ESLint, Pylint, golangci-lint
• Formatage : Prettier, Black, gofmt
• Analyse statique : SonarQube (sur le code source)
• Sécurité : détection de secrets, SAST sur le code source
• Documentation : vérification des liens, génération de docs

Tous ces jobs peuvent démarrer dès le premier instant du pipeline.

needs avec optional

Parfois, un job dans votre needs peut ne pas exister dans certains pipelines. Par exemple, security_scan ne s’exécute que sur la branche main (via rules). Sur une branche de feature, ce job n’existe pas.

Sans optional : GitLab refuse de créer le pipeline (“job not found”).

Avec optional: true : GitLab ignore silencieusement le job manquant.

security_scan:
  stage: test
  rules:
    - if: $CI_COMMIT_BRANCH == "main"  # N'existe que sur main
  script: ./scan.sh

deploy:
  needs:
    - job: build                        # Obligatoire, doit exister
    - job: security_scan
      optional: true                     # Optionnel : OK si le job n'existe pas

Comportement :

• Sur main : deploy attend build ET security_scan
• Sur feature-x : deploy attend seulement build (car security_scan n’existe pas)

Limites et cas particuliers

Limite de 50 jobs

Par défaut, needs accepte maximum 50 jobs. Au-delà, GitLab refuse de créer le pipeline. Cette limite existe pour éviter les pipelines trop complexes qui deviennent difficiles à débugger.

Si vous atteignez cette limite, c’est souvent un signe que votre pipeline devrait être découpé en pipelines parent-enfant.

Interaction avec parallel:

Si vous référencez un job qui utilise parallel: (ou parallel:matrix), votre job attend toutes les instances générées, pas une seule.

test:
  parallel: 3              # Génère test 1/3, test 2/3, test 3/3
  script: npm test

deploy:
  needs: ["test"]          # Attend les 3 jobs test

Pour cibler une instance spécifique, consultez le guide sur les matrices.

Dépendances dans le même stage

needs peut référencer des jobs du même stage. C’est utile quand deux jobs sont dans le même stage mais l’un dépend de l’autre.

build_lib:
  stage: build
  script: npm run build:lib

build_app:
  stage: build
  needs: ["build_lib"]     # Même stage, mais attend build_lib
  script: npm run build:app

Ne pas mélanger needs et dependencies

dependencies est l’ancien mot-clé pour contrôler les artefacts. Ne l’utilisez pas dans un job qui a déjà needs — les comportements peuvent entrer en conflit.

needs:project (avancé)

needs:project permet de télécharger des artefacts depuis d’autres pipelines ou projets. C’est utile pour les bibliothèques partagées, mais avec des contraintes : même instance GitLab, permissions adéquates, et la branche/ref doit être spécifiée.

Visualiser le DAG

GitLab affiche le graphe de dépendances dans l’interface :

1. Allez dans Build > Pipelines

2. Cliquez sur un pipeline

3. Sélectionnez l’onglet Needs (ou regardez le graphe qui montre les flèches)

Le graphe montre les vraies dépendances entre jobs, pas l’organisation par stages.

Exemples pratiques

Pipeline Node.js optimisé

stages:
  - prepare
  - quality
  - build
  - test
  - deploy

install:
  stage: prepare
  script: npm ci
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour

# Jobs de qualité : pas de dépendance, démarrent immédiatement
lint:
  stage: quality
  needs: []
  script: npm run lint

format_check:
  stage: quality
  needs: []
  script: npm run format:check

# Build : attend seulement install
build:
  stage: build
  needs: ["install"]
  script: npm run build
  artifacts:
    paths:
      - dist/

# Tests : en parallèle, chacun attend seulement ce dont il a besoin
unit_tests:
  stage: test
  needs: ["install"]
  script: npm test

e2e_tests:
  stage: test
  needs: ["build"]           # A besoin du build
  script: npm run test:e2e

# Deploy : attend les tests critiques, pas le lint
deploy_staging:
  stage: deploy
  needs: ["unit_tests", "build"]
  script: ./deploy.sh staging

Monorepo avec services indépendants

stages:
  - build
  - test
  - deploy

# Frontend et Backend buildent en parallèle
build_frontend:
  stage: build
  script: npm run build:frontend
  artifacts:
    paths:
      - frontend/dist/

build_backend:
  stage: build
  script: npm run build:backend
  artifacts:
    paths:
      - backend/target/

# Tests indépendants
test_frontend:
  stage: test
  needs: ["build_frontend"]
  script: npm run test:frontend

test_backend:
  stage: test
  needs: ["build_backend"]
  script: npm run test:backend

# Déploiements indépendants
deploy_frontend:
  stage: deploy
  needs: ["test_frontend"]
  script: ./deploy-frontend.sh

deploy_backend:
  stage: deploy
  needs: ["test_backend"]
  script: ./deploy-backend.sh

Le frontend et le backend sont complètement indépendants. Si le backend est lent, le frontend se déploie quand même.

Bonnes pratiques

1. Posez-vous la question : “De quoi ce job a-t-il VRAIMENT besoin ?”

Avant d’ajouter un job dans needs, demandez-vous : “Si ce job n’existait pas, le mien pourrait-il quand même s’exécuter ?” Si oui, ne l’ajoutez pas.

Exemple : deploy a-t-il besoin d’attendre lint ? Probablement pas — le lint vérifie la qualité du code, mais ne produit rien dont deploy a besoin.

2. Utilisez needs: [] agressivement

Chaque job qui peut démarrer immédiatement devrait avoir needs: []. C’est le levier le plus puissant pour accélérer vos pipelines.

Règle simple : si le job n’a besoin d’aucun fichier produit par un autre job, mettez needs: [].

3. Désactivez les artefacts inutiles

Quand vous attendez un job pour son statut (pas ses fichiers), utilisez artifacts: false :

deploy:
  needs:
    - job: lint
      artifacts: false   # On veut juste que lint soit passé, pas ses fichiers
    - job: build
      artifacts: true    # On a besoin du dossier dist/

4. Visualisez le graphe régulièrement

Après avoir modifié vos needs, regardez le graphe dans GitLab (onglet “Needs” du pipeline). Il montre les vraies dépendances et vous aide à repérer les erreurs.

5. Gardez les stages pour l’organisation

Même avec DAG, les stages restent utiles pour l’organisation visuelle. Regroupez les jobs par “catégorie” (build, test, deploy) même si leur exécution ne suit plus strictement cet ordre.

Erreurs fréquentes

Voici les problèmes les plus courants et comment les résoudre.

1. Dépendance circulaire (circular dependency)

Symptôme : Le pipeline refuse de se créer avec “circular dependency detected”.

Cause : Deux jobs se référencent mutuellement, créant une boucle impossible.

# ❌ INTERDIT : A attend B, mais B attend A
job_a:
  needs: ["job_b"]

job_b:
  needs: ["job_a"]

Solution : Revoyez l’architecture. Posez-vous la question : “Qui a vraiment besoin de qui ?” Souvent, un des deux needs est inutile.

2. Trop de dépendances (too many dependencies)

Symptôme : “needs cannot have more than 50 entries”.

Cause : Vous avez listé plus de 50 jobs dans un seul needs.

Solution :

• Simplifiez : ce job a-t-il vraiment besoin de 50 dépendances ?
• Regroupez : créez un job intermédiaire qui attend plusieurs jobs, puis dépendez de lui
• Self-managed : la limite est configurable dans les paramètres administrateur

3. Artefacts “disparus”

Symptôme : “file not found” alors que le job précédent les a bien créés.

Cause : Vous avez ajouté needs sans inclure le job qui produit les artefacts.

Rappel : Avec needs, vous ne recevez que les artefacts des jobs listés. Le comportement “magique” des stages précédents est désactivé.

# ❌ Problème : deploy attend lint, mais n'a pas les artefacts de build
deploy:
  needs: ["lint"]
  script: ls dist/           # ERREUR : dist/ n'existe pas !

# ✅ Solution : ajouter build dans needs
deploy:
  needs: ["lint", "build"]
  script: ls dist/           # OK : dist/ est téléchargé depuis build

4. needs: [] mais le job échoue

Symptôme : Vous avez mis needs: [] pour accélérer, mais le job échoue car il manque des fichiers.

Cause : Le job a en fait besoin d’artefacts d’un autre job.

Solution : Identifiez les fichiers manquants et ajoutez le job qui les produit dans needs.

# ❌ Le job a besoin de node_modules/, mais n'attend personne
test:
  needs: []
  script: npm test           # ERREUR : node_modules/ n'existe pas !

# ✅ Attendez le job qui installe les dépendances
test:
  needs: ["install"]
  script: npm test           # OK : node_modules/ est disponible

À retenir

1. needs définit les vraies dépendances, pas les stages
2. needs: [] = aucune dépendance, démarre immédiatement
3. Artefacts : avec needs, seuls ceux des jobs listés sont téléchargés
4. Limite : max 50 jobs dans needs par défaut
5. Pas de boucles — les dépendances doivent être acycliques
6. Ne pas mélanger needs et dependencies dans un même job
7. Visualisez le graphe dans GitLab pour valider

Prochaines étapes

Matrices de jobs Multiplier les exécutions avec parallel:matrix.

Pipelines parent-enfant Orchestrer les monorepos avec trigger.

Artefacts et cache Optimiser le partage de fichiers.

×

📖 Voir la documentation →