Valider un fichier .gitlab-ci.yml

Vous poussez votre .gitlab-ci.yml, le pipeline échoue avec une erreur de syntaxe, vous corrigez, vous re-poussez… et nouvelle erreur. Cette boucle frustrante est évitable : GitLab fournit plusieurs outils pour valider votre configuration avant le commit.

Ce guide vous présente 5 méthodes, de la plus simple (interface web) à la plus avancée (exécution locale). Choisissez celle qui correspond à votre workflow.

En 30 secondes

Méthode	Quand l’utiliser	Effort
Pipeline Editor	Modification rapide dans GitLab	⭐
CI Lint	Valider un YAML copié-collé	⭐
Extension VS Code	Développement quotidien	⭐⭐
API GitLab	Scripts d’automatisation	⭐⭐
gitlab-runner exec	Tester un job localement	⭐⭐⭐

Glissez pour voir

Ce que vous allez apprendre

À la fin de ce module, vous saurez :

• Utiliser le Pipeline Editor pour visualiser et valider votre pipeline
• Utiliser le CI Lint pour vérifier la syntaxe YAML
• Valider depuis VS Code avec l’extension GitLab Workflow
• Tester un job localement avant de le pousser

Prérequis

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

• Écrire un fichier .gitlab-ci.yml — structure stages/jobs/script

Le problème : le cycle “push → erreur → fix → push”

Sans validation locale, voici ce qui se passe typiquement :

1. Vous modifiez .gitlab-ci.yml
2. git add . && git commit -m "fix pipeline" && git push
3. Pipeline échoue : "jobs config should contain at least one visible job"
4. Vous corrigez
5. git add . && git commit -m "fix pipeline v2" && git push
6. Pipeline échoue : "invalid YAML syntax"
7. ...

Résultat : 5 commits pour une modification qui aurait pu être validée en 10 secondes.

Les outils de validation permettent de détecter ces erreurs avant le push — vous économisez du temps, des commits inutiles, et surtout de la frustration.

Méthode 1 : Pipeline Editor (recommandé)

Le Pipeline Editor est l’outil le plus pratique pour travailler sur votre .gitlab-ci.yml. Il combine édition, validation et visualisation en une seule interface.

1. Ouvrir le Pipeline Editor

   Dans votre projet GitLab, allez dans : Build → Pipeline editor

   Vous voyez votre fichier .gitlab-ci.yml actuel (ou un template si le fichier n’existe pas encore).

2. Modifier votre configuration

   L’éditeur offre de l’autocomplétion et de la coloration syntaxique pour le YAML GitLab CI/CD.

   À chaque frappe, GitLab valide automatiquement la syntaxe. Les erreurs apparaissent en temps réel.

3. Visualiser le pipeline

   Cliquez sur l’onglet “Visualize” pour voir la représentation graphique de votre pipeline :

   • Les stages et leur ordre
   • Les jobs dans chaque stage
   • Les dépendances (needs)

   

   C’est particulièrement utile quand vous utilisez les DAG et le parallélisme.

4. Voir la configuration complète (merged)

   L’onglet “View merged YAML” (ou “Full configuration”) affiche la configuration après résolution de tous les include.

   C’est indispensable quand vous utilisez des templates : vous voyez exactement ce que GitLab va exécuter.

5. Valider et committer

   Le bouton “Validate” vérifie :

   • La syntaxe YAML
   • Les références aux jobs (extends, needs)
   • Les noms de stages

   Si tout est valide, vous pouvez committer directement depuis l’interface.

Pipeline Editor = CI Lint + bonus

Le Pipeline Editor intègre le CI Lint et ajoute :

• La visualisation graphique du pipeline
• L’affichage du merged YAML (configuration après résolution des include)
• Le commit direct depuis l’interface

Si vous utilisez des templates (include/extends), le Pipeline Editor est indispensable pour voir la configuration finale.

Méthode 2 : CI Lint (interface web)

Le CI Lint est un validateur standalone, utile quand vous voulez tester un bout de YAML sans toucher à votre fichier actuel.

1. Accéder au CI Lint

   Dans votre projet : Build → Pipelines puis cliquez sur “CI lint” (en haut à droite).

   Alternative : accédez directement à l’URL https://gitlab.com/<votre-projet>/-/ci/lint

2. Coller votre configuration

   Collez le contenu de votre .gitlab-ci.yml dans la zone de texte.

3. Valider

   Cliquez sur “Validate”. GitLab affiche :

   • ✅ Syntax is correct si tout va bien
   • ❌ Syntax is incorrect avec le détail des erreurs

4. Simuler l’exécution (optionnel)

   Cochez la case “Simulate a pipeline created for the default branch” pour une validation plus poussée.

   La simulation évalue votre configuration comme si un pipeline push était créé sur la branche par défaut. Elle vérifie :

   • Les rules et conditions (dans ce contexte précis)
   • Les variables prédéfinies disponibles
   • Les références aux jobs

   ⚠️ Cela ne simule pas les autres contextes (MR, schedule, web trigger, etc.).

Ce que le CI Lint vérifie... et ne vérifie pas

Le CI Lint détecte :

• Erreurs de syntaxe YAML
• Clés/propriétés invalides
• Jobs invisibles (tous cachés ou exclus)
• needs vers un job inexistant
• rules qui excluent tous les jobs

Le CI Lint ne garantit PAS :

• L’accès aux registries/credentials
• La disponibilité des artifacts
• Le bon fonctionnement des scripts

→ Le lint ne remplace pas l’exécution réelle.

Exemple de validation

Configuration avec erreur :

stages:
  - build
  - test

build:
  stage: build
  script: npm run build

test:
  stage: test
  script: npm test
  needs: ["inexistant-job"]  # ❌ Ce job n'existe pas

Résultat du CI Lint :

Syntax is incorrect

'test' job needs 'inexistant-job' job, but it was not added to the pipeline

Méthode 3 : Extension VS Code (GitLab Workflow)

Pour ceux qui développent dans VS Code, l’extension GitLab Workflow permet de valider sans quitter l’éditeur.

1. Installer l’extension

   Dans VS Code, cherchez et installez : GitLab Workflow (éditeur : GitLab)

2. Configurer l’accès

   Créez un Personal Access Token (PAT) dans GitLab :

   • Allez dans User Settings → Access Tokens
   • Créez un token avec les scopes : api, read_user

   Dans VS Code, ouvrez la palette de commandes (Ctrl+Shift+P) et tapez :

   • GitLab: Set GitLab Personal Access Token
   • Entrez l’URL de votre GitLab (ex: https://gitlab.com)
   • Collez votre token

3. Valider votre fichier

   Ouvrez votre .gitlab-ci.yml, puis :

   • Palette de commandes (Ctrl+Shift+P)
   • GitLab: Validate GitLab CI/CD Configuration

   L’extension envoie le fichier à l’API GitLab et affiche le résultat.

Raccourci clavier

Configurez un raccourci clavier pour la validation (ex: Ctrl+Alt+V) :

1. File → Preferences → Keyboard Shortcuts
2. Cherchez GitLab: Validate
3. Assignez votre combinaison

Fonctionnalités bonus de l’extension

L’extension GitLab Workflow offre aussi :

• Vue des pipelines : voir le statut des pipelines en cours
• Vue des issues et MR : gérer les tickets sans quitter VS Code
• Liens rapides : cliquer sur l’icône GitLab ouvre la page du projet

Méthode 4 : API GitLab (pour l’automatisation)

L’API permet de valider programmatiquement, utile pour :

• Scripts de pre-commit
• Pipelines de vérification
• Outils personnalisés

Sécurité des tokens

Ne stockez jamais un token en dur dans un script versionné.

• Utilisez des variables d’environnement (export GITLAB_TOKEN=...)
• Scope minimal : api suffit pour la validation
• Activez une date d’expiration sur vos tokens

Valider via curl

# Variables d'environnement (à définir avant)
# export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"
GITLAB_URL="https://gitlab.com"
PROJECT_ID="12345"  # ou chemin encodé: "group%2Fproject"

# Envoyer le fichier pour validation
curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --header "Content-Type: application/json" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/ci/lint" \
  --data "{\"content\": $(cat .gitlab-ci.yml | jq -Rs .)}"

# Pour obtenir aussi le merged YAML (avec résolution des includes)
curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --header "Content-Type: application/json" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/ci/lint" \
  --data "{\"content\": $(cat .gitlab-ci.yml | jq -Rs .), \"include_merged_yaml\": true}"

Réponse en cas de succès :

{
  "valid": true,
  "merged_yaml": "...",
  "errors": [],
  "warnings": []
}

Réponse en cas d’erreur :

{
  "valid": false,
  "errors": ["jobs config should contain at least one visible job"],
  "warnings": []
}

Documentation API

Consultez la documentation officielle de l’API CI Lint pour les options avancées (ref, dry_run, include_jobs).

Script de pre-commit

Créez un hook Git qui valide avant chaque commit :

.git/hooks/pre-commit

#!/bin/bash
if [ -f ".gitlab-ci.yml" ]; then
  echo "Validation du pipeline GitLab..."

  RESULT=$(curl -s --request POST \
    --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
    --header "Content-Type: application/json" \
    "$GITLAB_URL/api/v4/projects/$PROJECT_ID/ci/lint" \
    --data "{\"content\": $(cat .gitlab-ci.yml | jq -Rs .)}")

  VALID=$(echo $RESULT | jq -r '.valid')

  if [ "$VALID" != "true" ]; then
    echo "❌ Pipeline invalide :"
    echo $RESULT | jq -r '.errors[]'
    exit 1
  fi

  echo "✅ Pipeline valide"
fi

Méthode 5 : Debug local avec gitlab-runner (avancé)

Outil de debug, pas de validation

gitlab-runner exec permet de déboguer un script de job isolé, pas de valider un pipeline complet. À utiliser avec recul — le comportement peut varier selon les versions.

Cette méthode est utile pour :

• Déboguer un script complexe sans pousser
• Tester sans consommer les minutes CI/CD
• Développer hors-ligne

Installer gitlab-runner

Téléchargez le binaire depuis gitlab-runner-downloads pour votre OS.

Linux (exemple) :

curl -L --output gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
chmod +x gitlab-runner
sudo mv gitlab-runner /usr/local/bin/

Exécuter un job localement

# Exécuter le job "build" avec l'executor Docker
gitlab-runner exec docker build

Exemple avec variables :

gitlab-runner exec docker build \
  --env CI_COMMIT_REF_SLUG="main" \
  --env CI_PROJECT_NAME="mon-projet"

Limitations de gitlab-runner exec

gitlab-runner exec a des limitations importantes :

• Pas de support pour needs : les dépendances entre jobs ne fonctionnent pas
• Pas de cache distribué : le cache est local uniquement
• Pas d’artifacts entre jobs : chaque job est indépendant
• Variables limitées : certaines variables CI_* ne sont pas disponibles

Cette commande est utile pour tester un job isolé, pas un pipeline complet.

Alternative : gitlabci-local (outil Python)

L’outil gitlabci-local offre une meilleure expérience pour l’exécution locale :

# Installation
pip install gitlabci-local

# Lancer le menu interactif
gitlabci-local

# Lancer tout le pipeline
gitlabci-local -p

# Lancer un job spécifique
gitlabci-local "build"

# Mode debug (conserve le conteneur)
gitlabci-local "build" --debug

Mode host

L’option -H ou --host exécute les scripts sans Docker, directement sur votre machine. Utile si vous avez déjà les outils installés localement.

gitlabci-local -H "build"

Workflow recommandé

1. Développement quotidien — Validez avec l’extension VS Code ou le CI Lint avant de committer

2. Pipeline avec templates/includes — Utilisez le Pipeline Editor pour voir le merged YAML (configuration finale)

3. Automatisation — Intégrez l’API lint dans un hook pre-commit ou un job CI de vérification

Quelle méthode choisir ?

Situation	Méthode recommandée
Modification rapide dans GitLab	Pipeline Editor
Développement quotidien	Extension VS Code
Vérifier un snippet YAML	CI Lint
Automatiser la validation	API GitLab
Déboguer un script complexe	gitlab-runner exec ou gitlabci-local

Glissez pour voir

Pour la plupart des développeurs, la combinaison Pipeline Editor + Extension VS Code couvre 95% des besoins.

Erreurs fréquentes

1. “jobs config should contain at least one visible job”

Cause : Tous vos jobs sont “cachés” (commencent par .) ou exclus par les rules.

Solution : Assurez-vous d’avoir au moins un job sans point au début du nom et sans rules qui l’exclut toujours.

2. “unknown key” ou “invalid property”

Cause : Typo dans un mot-clé YAML, ou utilisation d’une propriété qui n’existe pas.

Solution : Vérifiez l’orthographe dans la référence YAML GitLab CI/CD.

3. “needs ‘job’ was not added to the pipeline”

Cause : Un job référencé dans needs n’existe pas ou est exclu par ses rules.

Solution : Vérifiez que le job existe et que ses rules ne l’excluent pas dans le contexte actuel.

4. Je ne vois pas la configuration finale avec mes includes

Cause : Vous utilisez le CI Lint standalone sans demander le merged YAML.

Solution : Utilisez le Pipeline Editor → View merged YAML pour voir la configuration après résolution de tous les include.

À retenir

1. Pipeline Editor = outil #1 pour la plupart des cas (validation + visualisation + commit)
2. CI Lint = validation rapide d’un snippet sans toucher au fichier
3. Extension VS Code = validation sans quitter l’éditeur
4. API GitLab = automatisation (pre-commit hooks, scripts)
5. gitlab-runner exec = test d’un job isolé (mais pas de pipeline complet)
6. View merged YAML = indispensable quand vous utilisez des templates

Prochaines étapes

Debug : lire les logs Comprendre et naviguer dans les logs de vos jobs.

Runners GitLab CI/CD Comprendre qui exécute vos jobs.

Variables CI/CD Paramétrer vos jobs avec des variables.

×

📖 Voir la documentation →