Variables et secrets GitLab CI/CD

Vous avez besoin de passer des informations à vos jobs (URLs, tokens, configurations) sans les coder en dur ? Les variables GitLab CI/CD résolvent ce problème. Et pour les données sensibles (mots de passe, clés API), les options protected et masked assurent la sécurité.

Ce guide vous montre comment paramétrer vos pipelines et sécuriser vos secrets — deux compétences essentielles pour tout pipeline de production.

En 30 secondes

# Variable simple dans le YAML
variables:
  APP_ENV: "production"

# Utilisation dans un script
job:
  script:
    - echo "Environnement: $APP_ENV"
    - curl -sS -H "Authorization: Bearer $API_TOKEN" https://api.example.com

$APP_ENV vient du YAML, $API_TOKEN vient de l’interface GitLab (secret).

Ne loggez jamais vos tokens — utilisez -sS avec curl pour éviter les traces.

Ce guide est fait pour vous si…

Vous paramétrez un pipeline Passer des URLs, versions, configurations aux jobs.

Vous gérez des secrets Stocker clés API, mots de passe, certificats en sécurité.

Vous avez des variables en conflit Comprendre pourquoi une variable n'a pas la bonne valeur.

Vous séparez dev et prod Variables différentes selon l'environnement.

Prérequis

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

• Anatomie d’un .gitlab-ci.yml (stages, jobs, script)
• Syntaxe YAML de base

Les différents types de variables

GitLab CI/CD propose plusieurs types de variables, chacune adaptée à un besoin spécifique. Comprendre ces types est essentiel pour éviter les erreurs de configuration.

Variables d’environnement (les plus courantes)

Les variables d’environnement sont des chaînes de texte accessibles dans les scripts des jobs. Elles servent à stocker des configurations, des URLs, des versions — tout ce qui peut changer entre les environnements ou les exécutions.

variables:
  DATABASE_URL: "postgres://db.example.com:5432/myapp"
  APP_VERSION: "1.2.3"

test:
  script:
    - echo "Connexion à $DATABASE_URL"
    - echo "Version: $APP_VERSION"

Où les définir ?

Niveau	Portée	Cas d’usage
Dans le YAML	Ce pipeline uniquement	Configurations spécifiques au projet
Projet (Settings > CI/CD)	Tous les pipelines du projet	Secrets, URLs de prod
Groupe (Settings > CI/CD)	Tous les projets du groupe	Tokens partagés entre projets

Glissez pour voir

Variables de type fichier

Parfois, vous avez besoin d’un fichier plutôt qu’une simple chaîne : certificat SSL, fichier de configuration, clé privée. GitLab crée un fichier temporaire et stocke le chemin dans la variable.

deploy:
  script:
    # $DEPLOY_KEY contient le CHEMIN vers le fichier, pas le contenu
    - scp -i "$DEPLOY_KEY" app.zip user@server:/deploy/

Pour créer une variable fichier :

1. Allez dans Settings > CI/CD > Variables
2. Cliquez sur Add variable
3. Sélectionnez Type: File
4. Collez le contenu du fichier dans Value
5. GitLab créera le fichier à chaque job et mettra le chemin dans la variable

Piège courant

Avec une variable fichier, $MA_VARIABLE contient le chemin (/tmp/gitlab-ci-xxx), pas le contenu. Pour lire le contenu : cat "$MA_VARIABLE".

Variables protégées

Les variables protégées ne sont accessibles que dans les branches ou tags protégés. C’est la première ligne de défense pour vos secrets de production.

Pourquoi c’est important ?

Sans protection, n’importe qui peut créer une branche hack, ajouter echo $PROD_API_KEY dans le .gitlab-ci.yml, et voir votre secret dans les logs.

Avec une variable protégée, ce job échouera car la branche hack n’est pas protégée.

Pour protéger une variable :

1. Allez dans Settings > CI/CD > Variables
2. Cochez Protect variable
3. La variable ne sera injectée que dans les pipelines des branches/tags protégés

Variables masquées

Les variables masquées sont remplacées par [MASKED] dans les logs. Indispensable pour éviter les fuites accidentelles de secrets.

job:
  script:
    - echo "Token: $API_TOKEN"  # Affiche: Token: [MASKED]

Limites du masquage

Le masquage a des contraintes strictes :

• Une seule ligne, sans espaces dans la valeur
• Au moins 8 caractères
• Ne doit pas correspondre au nom d’une autre variable

Le masquage est une protection contre les fuites accidentelles, pas un contrôle de sécurité. Un acteur malveillant peut toujours exfiltrer un secret (encodage base64, exfiltration HTTP…).

Masked and Hidden (GitLab 17.6+)

Depuis GitLab 17.6, vous pouvez cocher Hidden en plus de Masked. La variable est alors invisible même dans l’interface Settings > CI/CD > Variables (seul l’admin peut la révéler). Utile pour les secrets très sensibles.

Variables CI_* prédéfinies

GitLab injecte automatiquement des dizaines de variables dans chaque job. Les plus utiles :

Variable	Contenu	Exemple d’utilisation
$CI_COMMIT_BRANCH	Nom de la branche	Conditions dans rules
$CI_COMMIT_SHA	Hash du commit	Versionner les artefacts
$CI_PIPELINE_ID	ID du pipeline	Identifier une exécution
$CI_JOB_TOKEN	Token temporaire	Accéder au registry GitLab
$CI_PROJECT_DIR	Chemin du checkout	Référencer des fichiers
$CI_ENVIRONMENT_NAME	Nom de l’environnement	Scripts de déploiement

Glissez pour voir

build:
  script:
    - echo "Build de la branche $CI_COMMIT_BRANCH"
    - docker build -t myapp:$CI_COMMIT_SHA .

Liste complète

Voir la documentation officielle des variables prédéfinies pour la liste exhaustive (plus de 100 variables).

Précédence des variables

Le problème : vous définissez DATABASE_URL dans le YAML, mais aussi dans les settings du projet. Laquelle gagne ?

GitLab applique une hiérarchie de précédence (du plus prioritaire au moins prioritaire) :

1. Variables de pipeline (UI, API, triggers, schedules, downstream)
2. Variables de projet (Settings > CI/CD)
3. Variables de groupe (le sous-groupe le plus proche gagne)
4. Variables d’instance (self-managed uniquement)
5. Variables issues de rapports dotenv (artefacts reports:dotenv)
6. Variables de job (dans variables: du job)
7. Variables globales du YAML (section variables: racine)
8. Variables de déploiement (liées aux environnements)
9. Variables prédéfinies (CI_*)

Politiques de sécurité

Si vous utilisez GitLab Ultimate avec des politiques de sécurité (Pipeline/Scan Execution Policies), leurs variables ont une priorité encore supérieure. Documentation précédence.

En pratique :

# YAML global : DATABASE_URL = "dev-db"
variables:
  DATABASE_URL: "dev-db"

test:
  # Si le projet définit DATABASE_URL = "test-db" dans Settings,
  # c'est "test-db" qui sera utilisé (projet > YAML)
  script:
    - echo $DATABASE_URL

Déboguer la précédence

Pour voir d’où vient une variable sans exposer vos secrets :

debug:
  script:
    - echo "CI_COMMIT_BRANCH=$CI_COMMIT_BRANCH"
    - echo "CI_PIPELINE_SOURCE=$CI_PIPELINE_SOURCE"
    - printenv | grep -E '^(CI_|APP_|ENV_)' | sort

Ne faites jamais export ou printenv sans filtre — cela afficherait tous les secrets dans les logs.

Pour les variables configurées : Settings > CI/CD > Variables.

Sécuriser les secrets

Un secret mal géré peut compromettre toute votre infrastructure. Voici les règles à suivre.

Règle 1 : Jamais de secret dans le YAML

# ❌ CATASTROPHE : le secret est dans l'historique Git
variables:
  API_TOKEN: "sk-1234567890abcdef"

# ✅ CORRECT : le secret vient de l'interface GitLab
job:
  script:
    - curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com

Règle 2 : Protected + Masked systématiquement

Pour tout secret :

1. Protected : limite l’accès aux branches/tags protégés
2. Masked : évite l’affichage accidentel dans les logs

Attention aux MR malveillantes

Une Merge Request qui modifie .gitlab-ci.yml peut exfiltrer même des variables masked/protected si le pipeline s’exécute. La vraie défense :

• Review obligatoire du code CI avant merge
• Restreindre qui peut lancer les pipelines sur branches protégées
• Utiliser merge_request_pipelines avec des variables réduites

Règle 3 : Scope environnement quand possible

Vous pouvez limiter une variable de projet à un environnement spécifique (production, staging, ou un wildcard comme review/*) :

1. Allez dans Settings > CI/CD > Variables
2. Dans Environment scope, sélectionnez l’environnement cible
3. La variable ne sera injectée que pour les jobs qui utilisent cet environnement

Variables de groupe

Le scoping par environnement pour les variables de groupe nécessite GitLab Premium (ajouté en 13.11).

deploy_prod:
  environment:
    name: production
  script:
    - echo $PROD_SECRET  # Disponible uniquement ici

Règle 4 : Rotation régulière

Changez vos secrets périodiquement. Si un secret est compromis, l’attaquant n’a qu’une fenêtre limitée.

Astuce : utilisez un gestionnaire de secrets (HashiCorp Vault, Infisical) pour automatiser la rotation.

Règle 5 : Préférer les pipeline inputs (GitLab 17.7+)

Depuis GitLab 17.7, les pipeline inputs (spec:inputs) offrent une alternative plus gouvernable aux variables de pipeline pour les paramètres non-secrets. Ils permettent de définir des valeurs par défaut, des validations et une documentation intégrée. Réservez les variables CI/CD aux vrais secrets.

Bonnes pratiques

Séparer les environnements

Utilisez des variables différentes pour dev, staging et prod :

stages:
  - test
  - deploy

test:
  stage: test
  variables:
    DATABASE_URL: $DEV_DATABASE_URL
  script:
    - pytest --db=$DATABASE_URL

deploy_prod:
  stage: deploy
  variables:
    DATABASE_URL: $PROD_DATABASE_URL
  environment:
    name: production
  script:
    - deploy.sh
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual

Nommer clairement

Utilisez des préfixes pour identifier l’origine et l’usage :

Préfixe	Signification
DEV_, STAGING_, PROD_	Environnement cible
SECRET_, KEY_, TOKEN_	Donnée sensible
APP_, DB_, API_	Composant concerné

Glissez pour voir

Exemple : PROD_DB_PASSWORD, DEV_API_BASE_URL

Documenter les variables requises

Dans votre README ou un fichier dédié, listez les variables à configurer :

## Variables CI/CD requises

| Variable | Type | Protected | Description |
|----------|------|-----------|-------------|
| `PROD_DEPLOY_KEY` | File | ✅ | Clé SSH pour le serveur de prod |
| `DOCKER_REGISTRY_TOKEN` | Var | ✅ | Token pour push sur le registry |
| `SLACK_WEBHOOK_URL` | Var | ❌ | Notifications (optionnel) |

Erreurs fréquentes

Symptôme	Cause probable	Solution
Variable vide dans le job	Variable protected, branche non protégée	Protéger la branche ou retirer la protection
Valeur inattendue	Précédence : projet override YAML	Vérifier Settings > CI/CD > Variables
Secret visible dans les logs	Variable non masquée	Activer Mask variable
$VAR affiché littéralement	Guillemets simples au lieu de doubles	Utiliser "$VAR" pas '$VAR'

Glissez pour voir

À retenir

1. Variables d’environnement pour les configurations, fichiers pour les certificats/clés.
2. Protected limite aux branches protégées, Masked cache dans les logs, Hidden masque dans l’UI.
3. Précédence : pipeline > projet > groupe > instance > dotenv > job YAML > global YAML > deploy > CI_*.
4. Jamais de secret dans le YAML — utilisez l’interface GitLab.
5. Jamais export ou printenv sans filtre — cela expose tous les secrets.
6. Scope environnement pour isoler les secrets dev/staging/prod.
7. Review des MR obligatoire — une MR malveillante peut exfiltrer vos secrets.

Testez vos connaissances

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

Conditions d'exécution (rules) Contrôler quand un job s'exécute avec rules, if, changes.

Déclencheurs Push, MR, tags, schedules — comprendre CI_PIPELINE_SOURCE.

Environnements Déployer sur dev, staging, prod avec variables scopées.

×

📖 Voir la documentation →