version: "1.0.0" name: gitlab-ci-guide description: Pipelines GitLab CI/CD, stages, jobs, runners, artifacts, environments et Auto DevOps. Se déclenche avec "GitLab CI", "gitlab-ci.yml", "pipeline GitLab", "runner GitLab", "GitLab CD".

Guide GitLab CI/CD

1. Concevoir la structure du pipeline

Définir les stages dans l'ordre d'exécution logique. Les jobs d'un même stage tournent en parallèle ; needs: casse cette contrainte pour du DAG.

stages:
  - build
  - test
  - analyze
  - deploy

Critères de découpage :

• Un stage = une responsabilité (ne pas mélanger build et test).
• Si un job doit démarrer avant la fin de son stage, utiliser needs: (DAG).
• Limiter à 6-7 stages max, au-delà, refactorer en pipelines enfants.

2. Écrire les jobs

Structure minimale d'un job de référence :

build:app:
  stage: build
  image: node:22-alpine
  before_script:
    - npm ci --cache .npm --prefer-offline
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 day
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/

Règles d'exécution, préférer `rules:` à `only/except` :

deploy:production:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: never
  environment:
    name: production
    url: https://app.example.com

3. Gérer les runners

Enregistrer un runner (GitLab 17+) :

gitlab-runner register \
  --url https://gitlab.example.com \
  --token $RUNNER_TOKEN \
  --executor docker \
  --docker-image alpine:latest \
  --tag-list "docker,linux,build"

Auto-scaling (on-premise) : utiliser le GitLab Runner Autoscaler (Fleeting + Taskscaler), avec les plugins AWS EC2, Google Compute Engine ou Azure. Pour Kubernetes : le runner Helm chart officiel.

L'ancien executor = "docker+machine" est déprécié depuis GitLab 17.5 et sera retiré en 20.0 (mai 2027) : Docker a abandonné Docker Machine, la brique sur laquelle il reposait. Les configurations config.toml qui traînent en ligne l'utilisent encore massivement.

4. Cache et artifacts

# Cache partagé entre branches, clé sur fichier de lock
cache:
  key:
    files:
      - yarn.lock
  paths:
    - node_modules/
  policy: pull-push   # pull-push par défaut ; "pull" pour jobs read-only
 
# Artifact de test coverage
test:unit:
  script: pytest --cov=src --cov-report=xml
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml
    expire_in: 7 days

Règle : toujours mettre expire_in sur les artifacts, sans ça, GitLab conserve par défaut selon la config instance (peut saturer le stockage).

`dependencies: []` sur les jobs de déploiement pour ne pas télécharger d'artifacts inutiles.

5. Pipelines avancés

DAG avec needs:

test:unit:
  stage: test
  needs: [build:app]   # démarre dès que build:app est terminé, pas toute la stage build
 
test:e2e:
  stage: test
  needs: [build:app, build:docker]

Pipelines enfants (monorepo)

trigger:backend:
  trigger:
    include: backend/.gitlab-ci.yml
    strategy: depend   # le parent attend la fin du pipeline enfant
  rules:
    - changes:
        - backend/**/*

Templates partagés

include:
  - project: 'infra/ci-templates'
    ref: main
    file: '/templates/docker-build.yml'
  - template: 'Security/SAST.gitlab-ci.yml'

6. Environnements et déploiements

deploy:review:
  stage: deploy
  script: ./scripts/deploy-review.sh $CI_ENVIRONMENT_SLUG
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.preview.example.com
    on_stop: stop:review
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
 
stop:review:
  stage: deploy
  script: ./scripts/teardown-review.sh $CI_ENVIRONMENT_SLUG
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  when: manual
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

7. Sécurité intégrée

Activer les scanners natifs via les templates officiels :

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml
  - template: Security/Container-Scanning.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml

Variables sensibles :

# Via CLI
glab variable set MY_SECRET "valeur" --masked --protected --project monprojet

Dans l'UI : Settings > CI/CD > Variables → cocher Masked + Protected.

Garde-fous et anti-patterns

Bonnes pratiques 2026

• Pipeline Component Catalog (GitLab 16.9+) : publier des composants réutilisables dans le Catalog plutôt que des templates include:remote.
• CI/CD Catalog : préférer component: à include:project: pour la versioning sémantique.
• `id_tokens:` (OIDC) : remplacer les tokens statiques pour l'auth cloud (AWS, Azure, GCP) par des tokens OIDC courts-vivants.
• Merge Train : activer sur les branches protégées à fort trafic pour éviter les régressions post-merge.
• `dast_configuration:` : pointer sur un environnement de review pour le DAST plutôt qu'une URL codée en dur.
• Valider le pipeline avant push : l'éditeur de pipeline GitLab (onglet Validate) simule la syntaxe et les règles. Pour une exécution locale réelle, l'outil tiers gitlab-ci-local.

gitlab-runner exec a été retiré en GitLab Runner 16.0. La commande n'existe plus ; elle reste citée dans beaucoup de documentations obsolètes.