CI/CD Components et Catalog GitLab

Vous cherchez des briques pipeline prêtes à l’emploi au lieu de tout écrire vous-même ? Les CI/CD Components (GA depuis GitLab 17.0) sont des blocs de pipeline réutilisables, versionnés et documentés. Vous les trouvez dans le CI/CD Catalog, vous les incluez avec include:component, et ils fonctionnent — comme installer un package npm pour vos pipelines.

Ce guide vous montre d’abord comment trouver et utiliser des composants existants, puis comment créer les vôtres pour votre équipe.

Ce que vous allez apprendre

Trouver des composants dans le CI/CD Catalog (gitlab.com ou self-hosted)
Utiliser un composant dans votre pipeline avec include:component
Comprendre la différence entre include classique et les components
Créer votre propre composant avec spec:inputs
Publier et versionner un composant dans le catalog

Dans quel contexte ?

Vous écrivez des pipelines GitLab CI/CD et vous vous retrouvez régulièrement à :

Copier-coller du YAML d’un projet à l’autre pour les jobs classiques (build Docker, lint, tests, SAST)
Chercher dans des repositories internes des templates partagés sans savoir lesquels existent
Maintenir des include: project: dont personne ne documente les variables attendues

Le CI/CD Catalog résout ces trois problèmes. C’est un registry de briques pipeline — cherchez, incluez, configurez.

Qu’est-ce qu’un CI/CD Component ?

Un CI/CD Component est un bloc de pipeline réutilisable hébergé dans un projet GitLab. Chaque composant :

Déclare ses paramètres via spec:inputs (nom, type, valeur par défaut, description)
Est versionné via les tags Git du projet (semver)
Est publié dans le CI/CD Catalog de l’instance GitLab
Est découvrable : recherche par nom, documentation intégrée, liste des inputs

`include` vs Components : quand utiliser quoi ?

Critère	`include`	Components
Complexité	Simple — inclure un fichier YAML	Plus structuré — projet dédié
Paramétrage	Variables d’environnement (non typées)	`spec:inputs` typés avec defaults
Versioning	`ref:` optionnel	Tags Git obligatoires pour le catalog
Documentation	README séparé (si on y pense)	Intégrée dans le catalog
Découvrabilité	Il faut connaître le chemin	Recherche dans le catalog
Validation	Aucune — le YAML est inclus tel quel	Inputs validés à l’évaluation
Cas d’usage	Partage interne équipe, petits projets	Partage cross-équipes, standards org

Règle pratique : si c’est utilisé par plus de 3 projets ou plus d’une équipe, un component est plus adapté qu’un include.

Trouver des composants dans le CI/CD Catalog

Où trouver le catalog ?

Le catalog est accessible depuis le menu latéral de GitLab :

GitLab.com : Allez sur Explore > CI/CD Catalog ou directement à l’URL https://gitlab.com/explore/catalog
Self-hosted : menu latéral Explore > CI/CD Catalog, ou https://votre-instance.example.com/explore/catalog

Le catalog affiche pour chaque composant :

Le README du projet (documentation)
Les versions disponibles (tags)
Le nombre de projets qui l’utilisent
Les inputs de chaque template (extraits automatiquement du spec:)

Composants officiels GitLab

GitLab maintient des composants officiels dans le namespace gitlab.com/components/. Quelques exemples utiles :

Composant	Usage	Référence
`components/sast`	Analyse statique de sécurité	`gitlab.com/components/sast@<version>`
`components/secret-detection`	Détection de secrets	`gitlab.com/components/secret-detection@<version>`
`components/code-quality`	Qualité de code	`gitlab.com/components/code-quality@<version>`
`components/container-scanning`	Scan d’images Docker	`gitlab.com/components/container-scanning@<version>`

Utiliser un composant

Syntaxe `include:component`

Incluez un composant dans votre .gitlab-ci.yml avec la directive include:component :

include:
  - component: $CI_SERVER_FQDN/components/sast@7.3.2
    inputs:
      stage: test

stages:
  - test
  - build

build:
  stage: build
  script: npm run build

Ce pipeline inclut le composant officiel SAST. Le composant crée automatiquement un ou plusieurs jobs dans le stage indiqué — vous n’avez pas à les écrire.

Format de référence

Le chemin d’un composant suit ce format :

<instance>/<namespace>/<projet>/<template>@<version>

Partie	Signification	Exemple
`<instance>`	Votre instance GitLab	`gitlab.com` ou `gitlab.example.com`
`<namespace>/<projet>`	Groupe et projet du composant	`components/sast`
`<template>`	Fichier dans `templates/` (sans `.yml`)	Omis si le projet n’a qu’un template
`@<version>`	Tag Git (version sémantique)	`@7.3.2`

Exemple : 2 composants dans un pipeline

include:
  # Scan SAST officiel — crée un job sast dans le stage test
  - component: $CI_SERVER_FQDN/components/sast@7.3.2
    inputs:
      stage: test

  # Détection de secrets — crée un job secret-detection dans le stage test
  - component: $CI_SERVER_FQDN/components/secret-detection@7.3.2
    inputs:
      stage: test

stages:
  - test
  - build

build:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build

Ce que le pipeline produit : 3 jobs au total — sast et secret-detection (créés par les composants), plus votre job build. Les composants gèrent tout (image, script, artifacts) — vous ne fournissez que les inputs.

Composant d’un projet interne

Pour un composant publié par votre équipe (pas un composant officiel) :

include:
  # Composant build interne — projet devops/ci-components-nodejs
  - component: $CI_SERVER_FQDN/devops/ci-components-nodejs/build@1.0.0
    inputs:
      image: node:20
      build_command: "npm run build"

  # Composant test du même projet (autre template)
  - component: $CI_SERVER_FQDN/devops/ci-components-nodejs/test@1.0.0
    inputs:
      image: node:20
      with_coverage: true

Ici, le projet ci-components-nodejs expose deux templates (build et test), chacun avec ses propres inputs.

Inputs obligatoires vs optionnels

Un input sans default est obligatoire. GitLab refuse le pipeline si vous ne le fournissez pas :

# ❌ Erreur : 'image' est requis (pas de default dans le composant)
include:
  - component: $CI_SERVER_FQDN/devops/ci-components-nodejs/build@1.0.0
    inputs:
      build_command: "npm run build"

# ✅ OK : 'image' fourni, 'build_command' a une valeur par défaut
include:
  - component: $CI_SERVER_FQDN/devops/ci-components-nodejs/build@1.0.0
    inputs:
      image: node:20

Pour savoir quels inputs existent et lesquels sont obligatoires, consultez la page du composant dans le catalog — les inputs sont listés avec leur type, leur description et leur éventuel default.

Voir les jobs créés par un composant

Un composant peut créer un ou plusieurs jobs. Pour savoir ce qui sera ajouté à votre pipeline :

Lisez la documentation du composant dans le catalog
Consultez le pipeline editor : allez dans Build > Pipeline editor et cliquez « Visualize ». GitLab résout les composants et affiche tous les jobs
Regardez le CI Lint : dans Build > Pipeline editor > CI Lint, collez votre .gitlab-ci.yml et validez — le résultat montre la configuration complète après résolution

Créer votre propre composant

Structure du projet

Un composant vit dans un projet GitLab dédié :

ci-components-nodejs/
├── templates/
│   ├── build.yml       # Composant build
│   ├── test.yml        # Composant test
│   └── lint.yml        # Composant lint
├── README.md           # Documentation (affichée dans le catalog)
└── .gitlab-ci.yml      # Pipeline pour tester le composant lui-même

Chaque fichier dans templates/ est un composant indépendant avec son propre spec:inputs.

Déclarer les inputs avec `spec:inputs`

Le cœur d’un composant est la section spec:inputs qui déclare l’interface :

spec:
  inputs:
    stage:
      default: build
      description: "Le stage dans lequel le job s'exécute"
    image:
      description: "Image Docker pour le build"
    build_command:
      default: "npm run build"
      description: "Commande de build"
    artifacts_path:
      default: "dist/"
      description: "Chemin des artefacts produits"
---
build:
  stage: $[[ inputs.stage ]]
  image: $[[ inputs.image ]]
  script:
    - $[[ inputs.build_command ]]
  artifacts:
    paths:
      - $[[ inputs.artifacts_path ]]
    expire_in: 30 days

Le séparateur --- sépare la déclaration des inputs du contenu YAML du composant.

Les types d’inputs

Type	Description	Exemple de valeur
`string`	Valeur texte (type par défaut)	`"node:20"`
`number`	Valeur numérique	`30`
`boolean`	`true` / `false`	`true`
`array`	Liste de valeurs	`["docker", "linux"]`

spec:
  inputs:
    image:
      description: "Image Docker pour les tests"
      type: string
    with_coverage:
      default: false
      description: "Activer le rapport de couverture"
      type: boolean
    timeout_minutes:
      default: 10
      description: "Timeout du job en minutes"
      type: number
---
test:
  image: $[[ inputs.image ]]
  script:
    - npm ci
    - npm test
  timeout: $[[ inputs.timeout_minutes ]] minutes
  rules:
    - if: $[[ inputs.with_coverage ]]
      variables:
        COVERAGE_FLAG: "--coverage"

Publier dans le CI/CD Catalog

Activer le catalog sur le projet

Allez dans Settings > General > Visibility, project features, permissions
Activez CI/CD Catalog resource
Ajoutez un README.md décrivant vos composants (c’est la page affichée dans le catalog)

Créez un tag Git pour la première version :

git tag -a v1.0.0 -m "Premier release du composant build Node.js"
git push origin v1.0.0

Pipeline de release recommandé

Ajoutez un pipeline qui publie automatiquement le composant quand vous créez un tag :

stages:
  - test
  - release

# Tester le composant avec lui-même (dogfooding)
test:component:
  stage: test
  trigger:
    include:
      - component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/build@$CI_COMMIT_SHA
        inputs:
          image: node:20
    strategy: depend

# Publier dans le catalog via une release GitLab
create-release:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  script:
    - echo "Publishing $CI_COMMIT_TAG to catalog"
  release:
    tag_name: $CI_COMMIT_TAG
    description: "Release $CI_COMMIT_TAG"
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/

Migrer un template `include` vers un component

Si vous avez déjà des templates partagés via include: project:, la migration est progressive :

Créez le projet component avec la structure templates/

Ajoutez spec:inputs pour formaliser les paramètres implicites

# Avant (template classique) — paramétrage via variables implicites
.build:
  image: $BUILD_IMAGE
  script:
    - $BUILD_COMMAND

# Après (component) — paramétrage explicite et documenté
spec:
  inputs:
    image:
      description: "Image Docker pour le build"
    build_command:
      default: "npm run build"
---
build:
  image: $[[ inputs.image ]]
  script:
    - $[[ inputs.build_command ]]

Publiez v1.0.0 dans le catalog

Migrez les consommateurs un par un :

# Avant
include:
  - project: 'devops/ci-templates'
    file: '/templates/build.yml'
    ref: 'main'

# Après
include:
  - component: $CI_SERVER_FQDN/devops/ci-components/build@1.0.0
    inputs:
      image: node:20

Conservez l’ancien template temporairement pour les projets non migrés

Bonnes pratiques

Nommage et organisation

Pratique	Recommandation
Un projet par domaine	`ci-components-nodejs`, `ci-components-docker`, `ci-components-terraform`
Un template par responsabilité	`build.yml`, `test.yml`, `lint.yml` — pas un monolithe
Groupe dédié	`devops/ci-components/` pour centraliser
README soigné	C’est la vitrine dans le catalog

Versioning sémantique

Changement	Version	Exemple
Fix sans changement d’interface	Patch `1.0.1`	Corriger un bug dans le script
Nouvel input optionnel	Minor `1.1.0`	Ajouter `with_coverage: false`
Suppression d’un input, changement de comportement	Major `2.0.0`	Renommer `build_cmd` en `build_command`

Sécurité

N’exposez pas de secrets dans les templates — les secrets doivent rester dans les variables CI/CD du projet consommateur
Validez les inputs : utilisez les types (number, boolean) pour empêcher les injections
Revue de code : un composant partagé à 50 projets mérite la même rigueur qu’une bibliothèque partagée

Dépannage

Symptôme	Cause probable	Solution
`component not found`	Mauvais chemin ou le projet n’est pas un catalog resource	Vérifier le chemin complet `<fqdn>/<namespace>/<project>/<template>@<tag>` et que le catalog est activé
`input 'xxx' is required`	Un input sans `default` n’est pas fourni	Consulter la page du composant dans le catalog pour voir les inputs obligatoires
`invalid input type`	Type attendu `number` mais valeur string fournie	Vérifier les types déclarés dans `spec:inputs`
Le composant ne s’affiche pas dans le catalog	Pas de tag Git publié	Créer un tag `vX.Y.Z` et vérifier les permissions du projet
Changement non visible après mise à jour	Version épinglée	Incrémenter le tag et mettre à jour `@version` chez les consommateurs
Ne sait pas quels jobs le composant crée	Documentation insuffisante	Utiliser Pipeline editor > Visualize ou CI Lint pour voir la config résolue

À retenir

Le CI/CD Catalog est le point d’entrée : cherchez-y des composants avant d’écrire du YAML — Explore > CI/CD Catalog
include:component remplace include: project: pour le partage cross-équipes — interface typée, versionnée, documentée
Utilisez $CI_SERVER_FQDN au lieu du nom de domaine en dur pour rendre vos pipelines portables
Chaque composant déclare son interface via spec:inputs — la syntaxe $[[ inputs.xxx ]] est évaluée avant la création du pipeline
Toujours épingler une version sémantique (@1.0.0) — jamais @main
Un composant crée des jobs complets dans votre pipeline — utilisez Pipeline editor pour visualiser le résultat
Les include classiques restent adaptés pour le partage intra-équipe de fichiers YAML simples
La migration include → components est progressive : les deux approches coexistent

Prochaines étapes

DAG et parallélisme Accélérez vos pipelines avec needs — exécutez les jobs selon leurs vraies dépendances.

include et templates Revoir les bases de include si besoin.

Pipelines parent-enfant Orchestrer des monorepos avec des pipelines dédiés par service.