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 en pointant sur une version précise, et le composant ajoute ses jobs à votre pipeline sans que vous ayez à les écrire.

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 ?

Les deux mécanismes réutilisent du YAML, mais ils ne visent pas le même besoin. Le tableau ci-dessous les oppose critère par critère ; lisez-le en gardant en tête une seule question, combien d'équipes partagent ce code. Un include reste un simple fichier inclus tel quel, sans interface ni validation, parfait pour du partage interne. Un component ajoute une interface typée via spec:inputs, un versionnement par tag Git obligatoire et une fiche dans le catalog, ce qui ne se justifie qu'au-delà de quelques projets. Les lignes Paramétrage et Découvrabilité concentrent l'essentiel de l'écart.

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

Cet exemple montre le cas courant où plusieurs composants cohabitent avec vos propres jobs. Chaque bloc - component: est indépendant et apporte ses jobs ; ici deux composants officiels (SAST et secret-detection) branchés sur le stage test, plus un job build que vous écrivez normalement. Le point à retenir en lisant ce YAML : vous ne définissez jamais les jobs des composants, vous ne fournissez que leurs inputs et le stage d'accueil. Veillez seulement à ce que le stage passé en input existe bien dans votre liste stages.

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@sha256:8f693eaa7e0a8e71560c9a82b55fd54c2ae920a2ba5d2cde28bac7d1c01c9ba5
      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@sha256:8f693eaa7e0a8e71560c9a82b55fd54c2ae920a2ba5d2cde28bac7d1c01c9ba5
      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

Déclarer un type sur chaque input n'est pas cosmétique : GitLab valide la valeur au moment de l'évaluation du pipeline et refuse un pipeline qui passe une chaîne là où un number est attendu. C'est cette validation qui distingue un component d'un include paramétré par variables d'environnement, où toute erreur de type passe inaperçue jusqu'à l'exécution. En l'absence de type, l'input est traité comme string. Un boolean typé est particulièrement utile dans une clause rules:if, comme le montre l'exemple ci-dessous.

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

Un projet ne devient pas visible dans le catalog par le seul fait de contenir des templates : deux conditions doivent être réunies. Il faut d'abord cocher l'option de ressource catalog dans les paramètres du projet, puis publier une release GitLab rattachée à un tag Git. Sans release taguée, le composant reste utilisable par son chemin mais n'apparaît pas dans la recherche du catalog. Le README joue aussi un rôle direct : c'est la page affichée aux visiteurs du catalog, il fait office de documentation.

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:v0.24.0
  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@sha256:8f693eaa7e0a8e71560c9a82b55fd54c2ae920a2ba5d2cde28bac7d1c01c9ba5

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

Bonnes pratiques

Nommage et organisation

L'organisation d'un composant se décide tôt, car la renommer après publication casse les chemins include de tous les consommateurs. Le principe directeur est le découpage par responsabilité : un template par tâche (build.yml, test.yml, lint.yml) plutôt qu'un fichier monolithique, ce qui permet à un projet de n'inclure que ce dont il a besoin. Regroupez ces projets dans un groupe dédié pour centraliser la découverte, et soignez le README, il reste la vitrine du composant dans le catalog.

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

Puisque les consommateurs épinglent une version précise, votre choix de numéro de version est un contrat. Le point qui casse le plus de pipelines est le passage en version majeure : dès que vous supprimez un input ou changez un comportement par défaut, incrémentez le premier chiffre, sinon une simple mise à jour de tag chez un consommateur fera échouer son pipeline sans prévenir. À l'inverse, un nouvel input optionnel avec une valeur par défaut reste rétrocompatible et ne mérite qu'une version mineure.

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é

Un composant partagé exécute son code dans le pipeline de chaque projet qui l'inclut : une faille dans un composant se propage à tous ses consommateurs. La règle la plus importante ici est la première : aucun secret dans le template lui-même, ni en clair ni en variable codée en dur, car le code du composant est lisible par tous. Les secrets restent dans les variables CI/CD du projet consommateur, que le job lit à l'exécution. Traitez un composant diffusé largement avec la même rigueur de revue qu'une bibliothèque partagée.

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

Les erreurs de composants se répartissent en deux familles faciles à distinguer. Soit le composant n'est pas trouvé ou n'apparaît pas dans le catalog, et la cause est presque toujours un chemin incorrect ou une release manquante. Soit le composant est trouvé mais rejette vos inputs, et il faut alors se reporter à la fiche du composant dans le catalog pour vérifier les inputs obligatoires et leurs types. En cas de doute sur ce que produit réellement un composant, l'outil Pipeline editor avec sa vue Visualize résout la configuration et affiche tous les jobs.

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

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

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.

CI/CD Components et Catalog GitLab

Ce que vous allez apprendre

Dans quel contexte ?

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

`include` vs Components : quand utiliser quoi ?

Trouver des composants dans le CI/CD Catalog

Où trouver le catalog ?

Composants officiels GitLab

Utiliser un composant

Syntaxe `include:component`

Format de référence

Exemple : 2 composants dans un pipeline

Composant d'un projet interne

Inputs obligatoires vs optionnels

Voir les jobs créés par un composant

Créer votre propre composant

Structure du projet

Déclarer les inputs avec `spec:inputs`

Les types d'inputs

Publier dans le CI/CD Catalog

Activer le catalog sur le projet

Pipeline de release recommandé

Migrer un template `include` vers un component

Bonnes pratiques

Nommage et organisation

Versioning sémantique

Sécurité

Dépannage

À retenir

Testez vos connaissances

Contrôle de connaissances

Informations

Vérification

Profil de compétences

Quoi faire maintenant

Prochaines étapes

CI/CD Components et Catalog GitLab

Ce que vous allez apprendre

Dans quel contexte ?

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

include vs Components : quand utiliser quoi ?

Trouver des composants dans le CI/CD Catalog

Où trouver le catalog ?

Composants officiels GitLab

Utiliser un composant

Syntaxe include:component

Format de référence

Exemple : 2 composants dans un pipeline

Composant d'un projet interne

Inputs obligatoires vs optionnels

Voir les jobs créés par un composant

Créer votre propre composant

Structure du projet

Déclarer les inputs avec spec:inputs

Les types d'inputs

Publier dans le CI/CD Catalog

Activer le catalog sur le projet

Pipeline de release recommandé

Migrer un template include vers un component

Bonnes pratiques

Nommage et organisation

Versioning sémantique

Sécurité

Dépannage

À retenir

Testez vos connaissances

Contrôle de connaissances

Informations

Profil de compétences

Quoi faire maintenant

Prochaines étapes

`include` vs Components : quand utiliser quoi ?

Syntaxe `include:component`

Déclarer les inputs avec `spec:inputs`

Migrer un template `include` vers un component