Templates GitLab CI/CD (include, extends)

Vous copiez-collez les mêmes jobs entre vos projets ? Les templates GitLab CI/CD permettent de centraliser et réutiliser vos configurations. Modifiez en un seul endroit, propagez partout.

En 30 secondes

# Inclure un template depuis un autre projet
include:
  - project: 'devops/ci-templates'
    file: '/templates/nodejs.yml'
    ref: 'v1.0.0'

# Utiliser un job du template
build:
  extends: .nodejs_build
  variables:
    NODE_VERSION: "18"

Ce guide est fait pour vous si…

Vous gérez plusieurs projets Même configuration Node.js/Python/Docker partout.

Vous voulez centraliser Une source de vérité pour vos pipelines.

Vous versionnez vos templates ref: v1.0.0 pour contrôler les mises à jour.

Vous conditionnez les includes Inclure selon la branche ou une variable.

Prérequis

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

• extends et anchors
• Variables GitLab CI/CD

Pourquoi factoriser ?

Sans factorisation, vous avez :

• Duplication : mêmes jobs copiés dans 50 projets
• Incohérence : chaque projet diverge avec le temps
• Maintenance pénible : une mise à jour = 50 merge requests

Avec les templates :

• Une source de vérité : un seul endroit à maintenir
• Cohérence garantie : tous les projets utilisent la même version
• Mise à jour simple : modifiez le template, tous les projets en bénéficient

include : importer des fichiers

Types d’include

Type	Syntaxe	Source
local	local: '/path/file.yml'	Fichier dans le même repo
project	project: 'group/project'	Fichier dans un autre projet GitLab
remote	remote: 'https://...'	URL externe
template	template: 'Jobs/Build.gitlab-ci.yml'	Templates officiels GitLab

Glissez pour voir

Include local

Fichiers dans le même repository :

.gitlab-ci.yml

include:
  - local: '/ci/build.yml'
  - local: '/ci/test.yml'
  - local: '/ci/deploy.yml'

stages:
  - build
  - test
  - deploy

ci/build.yml

build:
  stage: build
  script:
    - npm ci
    - npm run build

Include project (autre repo GitLab)

Importer depuis un projet centralisé :

include:
  - project: 'devops/ci-templates'
    file: '/templates/nodejs.yml'
    ref: 'main'

Options :

Option	Description
project	Chemin du projet (group/subgroup/project)
file	Chemin du fichier dans le projet
ref	Branche, tag ou commit (défaut: branche par défaut)

Glissez pour voir

Include remote

Fichier externe via URL :

include:
  - remote: 'https://example.com/templates/ci.yml'

Sécurité

Les includes remote peuvent poser des risques de sécurité. Préférez les includes project pour les ressources internes.

Templates officiels GitLab

GitLab fournit des templates prêts à l’emploi :

include:
  - template: Jobs/Build.gitlab-ci.yml
  - template: Security/SAST.gitlab-ci.yml

Liste des templates : GitLab CI/CD Templates

Templates centralisés dans un projet dédié

Structure recommandée

Créez un projet devops/ci-templates avec cette structure :

ci-templates/
├── templates/
│   ├── nodejs.yml
│   ├── python.yml
│   ├── docker.yml
│   └── deploy/
│       ├── kubernetes.yml
│       └── aws.yml
├── jobs/
│   ├── lint.yml
│   ├── test.yml
│   └── security.yml
└── README.md

Exemple de template Node.js

templates/nodejs.yml

variables:
  NODE_VERSION: "18"    # Valeur par défaut, surchargeable par le projet

# Job de base pour Node.js (à étendre)
.nodejs_base:
  image: "node:${NODE_VERSION}"
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/              # Cache du gestionnaire, pas node_modules/
    policy: pull
  before_script:
    - npm ci --cache .npm --prefer-offline

# Job d'installation
.nodejs_install:
  extends: .nodejs_base
  script:
    - npm ci --cache .npm --prefer-offline
  cache:
    policy: pull-push
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour

# Job de build
.nodejs_build:
  extends: .nodejs_base
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

# Job de test
.nodejs_test:
  extends: .nodejs_base
  script:
    - npm test
  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'

Cache npm : .npm/ plutôt que node_modules/

En production, cachez le répertoire .npm/ (cache du gestionnaire) plutôt que node_modules/. C’est plus stable et évite les problèmes de compatibilité entre OS. Même principe pour pip (.cache/pip), Maven (.m2), Go (go/pkg/mod).

Utilisation dans un projet

mon-projet/.gitlab-ci.yml

include:
  - project: 'devops/ci-templates'
    file: '/templates/nodejs.yml'
    ref: 'v1.0.0'

stages:
  - install
  - build
  - test

install:
  stage: install
  extends: .nodejs_install

build:
  stage: build
  extends: .nodejs_build
  needs: ["install"]

test:
  stage: test
  extends: .nodejs_test
  needs: ["install"]

Versionner avec ref

Contrôlez quelle version du template est utilisée :

include:
  # Version stable pour la prod
  - project: 'devops/ci-templates'
    file: '/templates/nodejs.yml'
    ref: 'v1.0.0'

  # Ou une branche pour les tests
  - project: 'devops/ci-templates'
    file: '/templates/nodejs.yml'
    ref: 'feature/new-template'

Stratégie recommandée :

Environnement	Ref	Description
Production	v1.0.0 (tag)	Version stable, testée
Staging	main	Dernière version
Dev	feature/*	Tests de nouvelles features

Glissez pour voir

Includes conditionnels

GitLab supporte include:rules pour conditionner les fichiers inclus (vérifiez la disponibilité selon votre version) :

include:
  # Toujours inclus
  - local: '/ci/base.yml'

  # Seulement si variable définie
  - local: '/ci/security.yml'
    rules:
      - if: '$ENABLE_SECURITY == "true"'

  # Seulement sur main
  - local: '/ci/deploy-prod.yml'
    rules:
      - if: '$CI_COMMIT_BRANCH == "main"'

Compatibilité version

Les fonctionnalités include:rules et include:integrity ont été ajoutées progressivement. Consultez la documentation officielle pour vérifier la disponibilité sur votre version GitLab.

Surcharger les templates

Les jobs qui étendent un template peuvent surcharger n’importe quelle propriété :

include:
  - project: 'devops/ci-templates'
    file: '/templates/nodejs.yml'

build:
  extends: .nodejs_build
  variables:
    NODE_VERSION: "20"          # Surcharge la version
  script:
    - npm run build:prod        # Surcharge le script
  after_script:
    - echo "Build terminé"      # Ajoute un after_script

Outils recommandés

To Be Continuous

Plateforme de templates GitLab CI/CD maintenus par des experts :

• Templates prêts à l’emploi pour de nombreuses technologies
• Bien documentés et régulièrement mis à jour
• Supporte les workflows modernes (Gitflow, trunk-based)

Site : to-be-continuous.gitlab.io

R2DevOps

Catalogue de templates avec audit de conformité :

• Catalogue visuel de templates
• Détection de secrets et variables non protégées
• Audit de conformité automatique

Site : r2devops.io

Sécurité des templates

Pinner par tag ou commit

Utilisez toujours ref pour éviter les surprises :

include:
  # ✅ Version pinnée (recommandé)
  - project: 'devops/ci-templates'
    file: '/templates/nodejs.yml'
    ref: 'v1.0.0'                      # Tag

  # ✅ Commit spécifique (maximum de contrôle)
  - project: 'devops/ci-templates'
    file: '/templates/nodejs.yml'
    ref: 'a1b2c3d4e5f6'                # SHA commit

  # ⚠️ Branche (peut changer)
  - project: 'devops/ci-templates'
    file: '/templates/nodejs.yml'
    ref: 'main'

Vérifier l’intégrité (GitLab 17.9+)

include:integrity permet de vérifier le hash SHA256 du fichier inclus :

include:
  - remote: 'https://example.com/templates/ci.yml'
    integrity: 'sha256:abc123def456...'    # Hash du fichier

Éviter les includes remote non maîtrisés

Risques des include: remote :

• Le fichier peut être modifié à tout moment
• Pas de contrôle de version
• Risque de supply chain attack

Préférez : include: project avec ref pinné, ou copiez le template dans votre organisation.

Bonnes pratiques

1. Préfixez les jobs cachés : .nodejs_build, .python_test pour éviter les conflits

2. Documentez vos templates : README avec exemples d’utilisation

3. Versionnez avec des tags : v1.0.0, v1.1.0 pour la stabilité

4. Testez vos templates : créez des projets de test qui utilisent vos templates

5. Variables par défaut dans variables: : définissez les valeurs par défaut explicitement, puis référencez avec ${VAR}

6. Séparez par technologie : un fichier par langage/framework

7. Pinez vos refs : utilisez des tags ou commits, pas des branches

Erreurs fréquentes

Erreur	Cause	Solution
file not found	Mauvais chemin dans include	Vérifier le chemin (commence par /)
project not found	Pas d’accès au projet	Vérifier les permissions
Job non trouvé	Le template ne définit pas ce job	Vérifier le nom du job dans le template
Conflit de jobs	Même nom dans plusieurs includes	Renommer ou utiliser des préfixes
Variables non surchargées	Mauvaise syntaxe	Utiliser variables: au niveau du job

Glissez pour voir

À retenir

1. include: local pour les fichiers du même repo
2. include: project pour les templates centralisés
3. ref pour versionner — pinez par tag ou commit
4. extends pour hériter et surcharger
5. Préfixer les jobs cachés (.nodejs_, .python_)
6. Éviter include: remote non maîtrisé (risque supply chain)
7. Cacher .npm/ (ou équivalent) plutôt que node_modules/

Prochaines étapes

DAG et parallélisme Optimiser l'exécution avec needs.

Pipelines parent-enfant Orchestrer les monorepos.

×

📖 Voir la documentation →