Personnalisation de GitLab CI/CD¶

Personnalisez le pipeline automatisé de construction et de déploiement pour GitLab Pages.

Aperçu¶

Lorsque vous publiez un site web Silex sur GitLab Pages, Silex crée un fichier .gitlab-ci.yml dans votre dépôt. Ce fichier définit un pipeline CI/CD qui :

Installe les dépendances
Exécute build awesome (propulsé par Eleventy) pour construire le site statique
Déploie sur GitLab Pages

Vous pouvez personnaliser le pipeline pour ajouter des étapes de construction, de la mise en cache, des domaines personnalisés ou une intégration avec des services externes.

Prérequis¶

Site web stocké dans GitLab (via le connecteur de stockage GitLab)
Compréhension de base de GitLab CI/CD
Connaissances des scripts shell et de Node.js

Pipeline par défaut¶

Silex génère un .gitlab-ci.yml standard :

image: node:18

stages:
  - build
  - deploy

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

cache:
  paths:
    - .npm
    - node_modules

before_script:
  - npm ci --prefer-offline --no-audit

build:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - _site/
    expire_in: 1 week

pages:
  stage: deploy
  script:
    - echo "Deploying to GitLab Pages"
  artifacts:
    paths:
      - public/
  environment:
    name: production
    url: https://$CI_PROJECT_NAMESPACE.gitlab.io/$CI_PROJECT_NAME
  only:
    - main

Personnaliser le pipeline¶

Modifiez .gitlab-ci.yml directement dans votre dépôt GitLab.

Ajouter une étape de construction¶

Exécutez des commandes personnalisées après la construction par défaut :

build:
  stage: build
  script:
    - npm run build
    - npm run lint          # Add linting
    - npm run test          # Add tests
  artifacts:
    paths:
      - _site/

Variables d'environnement¶

Passez des secrets ou de la configuration au pipeline :

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"
  CUSTOM_ENV_VAR: "value"    # Custom variable

Ou définissez dans les paramètres du projet GitLab :

Allez dans Settings → CI/CD → Variables
Ajoutez une variable : MY_SECRET = secret-value
Utilisez dans le pipeline : $MY_SECRET

Variables protégées (uniquement sur les branches protégées) :

variables:
  DEPLOY_KEY:
    value: "secret"
    protected: true

Rétention des artefacts¶

Contrôlez la durée de conservation des artefacts de construction :

artifacts:
  paths:
    - _site/
  expire_in: 30 days    # Keep for 30 days

Mise en cache des dépendances¶

Accélérez les constructions en mettant en cache les paquets npm :

cache:
  paths:
    - .npm
    - node_modules/
  policy: pull-push      # Pull from cache, push new items

Ou mettez en cache uniquement sur des branches spécifiques :

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/
  policy: pull           # Only pull from cache (never update)

Utiliser différentes versions de Node¶

Construisez avec une version spécifique de Node.js :

image: node:18          # Use Node 18

Ou utilisez une matrice pour tester plusieurs versions :

build:
  parallel:
    matrix:
      - NODE_VERSION: [16, 18, 20]
  image: node:$NODE_VERSION
  script:
    - npm run build

Exécuter des scripts en parallèle¶

Accélérez le pipeline en exécutant des étapes indépendantes en parallèle :

stages:
  - build
  - test
  - deploy

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

lint:
  stage: test
  script:
    - npm run lint

test:
  stage: test
  script:
    - npm run test

pages:
  stage: deploy
  script:
    - echo "Deploy"

Exécution conditionnelle¶

N'exécutez certaines tâches que sur des branches spécifiques :

deploy_production:
  stage: deploy
  script:
    - npm run build:prod
  only:
    - main       # Only on main branch

deploy_staging:
  stage: deploy
  script:
    - npm run build:staging
  only:
    - develop    # Only on develop branch

deploy_manual:
  stage: deploy
  script:
    - npm run build
  when: manual   # Requires manual trigger

Utiliser des images Docker¶

Construisez avec une image Docker personnalisée :

image: mycompany/silex-builder:latest

# Or use multiple images for different jobs
build:
  image: node:18-alpine
  script:
    - npm run build

test:
  image: ruby:3.0
  script:
    - bundle install
    - bundle exec rspec

Inclure des fichiers externes¶

Partagez la configuration CI/CD entre les dépôts :

include:
  - remote: 'https://example.com/ci-templates/silex.yml'
  - project: 'my-org/ci-templates'
    file: 'silex-base.yml'
  - local: '.gitlab/ci-base.yml'

Notifications et intégrations¶

Envoyez des notifications après les constructions :

pages:
  stage: deploy
  script:
    - npm run build
  after_script:
    - 'curl -X POST https://hooks.slack.com/... -d "{"text":"Deployment complete"}"'

Ou intégrez avec des services externes :

after_script:
  - 'curl -X POST https://api.example.com/deployments'

Configuration avancée¶

Construction personnalisée pour build awesome¶

Si votre configuration build awesome nécessite un traitement spécial :

build:
  stage: build
  script:
    - npm ci
    - npm run eleventy    # Custom 11ty build command
    - npm run minify-css  # Post-processing
  artifacts:
    paths:
      - _site/

Étape de pré-installation¶

Exécutez une configuration avant les constructions :

before_script:
  - npm ci --prefer-offline
  - npm run setup        # Custom setup

Utiliser le flag silexOverwrite¶

Contrôlez si les fichiers existants sont écrasés lors de la republication :

variables:
  SILEX_OVERWRITE: "true"    # Overwrite on publish

Définissez dans les paramètres de publication Silex ou passez via une variable CI/CD.

Étapes de déploiement personnalisées¶

Ajoutez des tâches de nettoyage ou post-déploiement :

pages:
  stage: deploy
  script:
    - echo "Deploying"
  after_script:
    - echo "Cleaning up"
    - rm -rf ./temp/
  artifacts:
    paths:
      - public/

Configuration de domaine personnalisé¶

Configurez un domaine personnalisé pour GitLab Pages :

pages:
  environment:
    name: production
    url: https://my-custom-domain.com    # Custom domain
  artifacts:
    paths:
      - public/

Dans les paramètres du projet GitLab, ajoutez également le domaine :

Deployments → Pages
Domains → New domain
Saisissez le domaine et suivez la configuration DNS

Redirections d'URL¶

GitLab Pages prend en charge un fichier _redirects à la racine du site publié, utilisant la même syntaxe que les redirections Netlify. C'est utile pour :

Préserver les anciennes URL lorsque vous réorganisez la documentation ou les pages
Rediriger des URL courtes vers des chemins complets
Gérer le contenu déplacé sans casser les favoris ou les liens des moteurs de recherche

Créez un fichier _redirects dans votre dépôt :

# _redirects
/old-page    /new-page    301
/blog/:slug  /articles/:slug  301

Chaque ligne comporte trois champs séparés par des espaces : l'ancien chemin, le nouveau chemin et le code HTTP (301 pour une redirection permanente, 302 pour temporaire).

Assurez-vous que le fichier se retrouve dans le répertoire public/ après la construction. Ajoutez une étape de copie à votre pipeline si nécessaire :

pages:
  script:
    - npm ci
    - npx @11ty/eleventy --input=public --output=_site
    - cp _redirects _site/ 2>/dev/null || true
    - rm -rf public && mv _site public

Consultez la documentation des redirections GitLab Pages pour la syntaxe complète (règles splat, paramètres de requête, redirections forcées).

Construction et déploiement vers plusieurs environnements¶

Déployez en production et en staging :

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - _site/

deploy_prod:
  stage: deploy
  script:
    - echo "Deploy to production"
  environment:
    name: production
    url: https://prod.example.com
  only:
    - main

deploy_staging:
  stage: deploy
  script:
    - echo "Deploy to staging"
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - develop

Exemple complet¶

Un .gitlab-ci.yml complet avec tests, linting et mise en cache :

image: node:18-alpine

stages:
  - install
  - build
  - test
  - deploy

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"
  NODE_ENV: "production"

cache:
  key:
    files:
      - package-lock.json
  paths:
    - .npm
    - node_modules/

install:
  stage: install
  script:
    - npm ci --prefer-offline --no-audit

build:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - _site/
    expire_in: 1 week

lint:
  stage: test
  script:
    - npm run lint:css
    - npm run lint:js
  allow_failure: true

test:
  stage: test
  script:
    - npm run test
  coverage: '/Coverage: (\d+)%/'

pages:
  stage: deploy
  script:
    - mkdir -p public
    - cp -r _site/* public/
  artifacts:
    paths:
      - public/
  environment:
    name: production
    url: https://$CI_PROJECT_NAMESPACE.gitlab.io/$CI_PROJECT_NAME
  only:
    - main

Dépannage¶

Le pipeline échoue avec "npm not found"¶

Assurez-vous que l'image Docker inclut Node.js :

image: node:18    # Correct
# NOT: image: ubuntu:latest

Les artefacts ne sont pas déployés¶

Vérifiez :

Les artefacts sont dans le répertoire public/
La tâche est dans l'étape deploy
La tâche est nommée pages
La règle only autorise la branche

Le pipeline est lent¶

Optimisez :

Ajoutez la mise en cache pour node_modules/ et .npm
Utilisez des images Docker plus petites (variantes alpine)
Exécutez les tâches en parallèle lorsque c'est possible
Mettez en cache les dépendances externes

L'URL d'environnement ne fonctionne pas¶

Assurez-vous :

Le domaine est correct : https://username.gitlab.io/project-name
Le DNS du domaine personnalisé est configuré
GitLab Pages est activé dans les paramètres du projet

Voir aussi¶

Documentation GitLab CI/CD — Référence complète
Documentation GitLab Pages — Configuration de Pages
Personnalisation de la construction build awesome
Hooks de publication

Éditer cette page sur GitLab