Aller au contenu

Configurer le rebuild hebdomadaire de la doc

Vous êtes mainteneur·se de Kirexo et vous voulez rafraîchir le rendu de la documentation chaque semaine sans attendre la prochaine release. Une schedule GitLab dédiée déclenche le job pages avec REBUILD_DOCS=true : il reconstruit le site figé sur le dernier tag YYYYMMDDHHMM avec l'image kirexo-docs à jour (patch de mkdocs-material, plugins…).

Le contenu déployé ne change pas

Ce schedule ne sert qu'à régénérer le rendu. Le job repositionne HEAD sur le dernier tag de release avant de builder, donc la doc déployée reste exactement celle de la version actuellement en production — pas la doc en cours sur main. Si une page a été modifiée depuis le dernier tag, elle ne sortira sur doc.kirexo.app qu'à la prochaine release.

L'intérêt : profiter d'une mise à jour de l'environnement de build (image kirexo-docs rebuildée par Renovate / sur évolution de mkdocs/Dockerfile) sans avoir à attendre une nouvelle release. Par exemple, un patch mkdocs-material qui corrige le rendu d'un composant : la doc publique en bénéficie dès la prochaine exécution du schedule.

Prérequis

  • Vous avez les droits Maintainer ou Owner sur le projet GitLab.
  • Au moins un tag YYYYMMDDHHMM existe dans le repo (cf. Créer un tag de release). Sans tag, le job sort en succès sans rien faire (rien à régénérer).
  • Le domaine GitLab Pages est déjà configuré (cf. Configurer le domaine GitLab Pages) — sinon la doc reconstruite ne sera servie nulle part.
  • Le fichier .gitlab/ci/release.yml est présent dans le repo et le job pages y porte la rule $CI_PIPELINE_SOURCE == "schedule" && $REBUILD_DOCS == "true" (cf. Job pages).

Créer la schedule

  1. Dans le projet GitLab, aller dans Build → Pipeline schedules.
  2. Cliquer sur New schedule.

  3. Renseigner les champs suivants :

    Champ Valeur
    Description Doc weekly rebuild
    Interval pattern 0 4 * * 1 (lundi 4 h UTC — soit 5 h ou 6 h en France selon la saison)
    Cron timezone UTC (laisser par défaut)
    Target branch main
    Variables Une variable REBUILD_DOCS de type Variable (non-file), valeur true.
    Activated Coché

  4. Cliquer sur Save pipeline schedule.

Pourquoi 4 h UTC et pas 5 h ?

La schedule de l'audit de sécurité quotidien tourne à 0 5 * * * UTC. Décaler le rebuild de la doc à 4 h évite que les deux pipelines ne tournent en même temps sur les runners partagés. Si vous adaptez l'un, pensez à l'autre.

Comprendre la rule

Le job pages (.gitlab/ci/release.yml) porte deux rules cumulables :

rules:
  - if: $CI_COMMIT_TAG =~ /^[0-9]{12}$/
  - if: '$CI_PIPELINE_SOURCE == "schedule" && $REBUILD_DOCS == "true"'

La variable REBUILD_DOCS=true est ce qui distingue cette schedule des autres schedules quotidiennes (audit, Renovate, version-check, container scanning) qui tournent aussi sur main mais sans cette variable. Sans le filtre $REBUILD_DOCS == "true", la schedule quotidienne d'audit aurait redéployé la doc tous les jours — comportement non voulu et coûteux en runner.

Ce que fait le job sur ce déclencheur

  1. Le before_script du job détecte le contexte schedule (if [ "$CI_PIPELINE_SOURCE" = "schedule" ]; then).

  2. Il liste les tags au format YYYYMMDDHHMM triés du plus récent au plus ancien :

    git tag --list --sort=-creatordate '[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]' | head -1

  3. Si aucun tag n'est trouvé, le job sort en 0 (rien à faire — typiquement avant la première release).

  4. Sinon, git checkout --detach $LAST_TAG repositionne HEAD sur ce commit en HEAD détaché (pas besoin de toucher à une branche locale).
  5. mkdocs build --strict -d public génère le site. GitLab Pages collecte l'artifact public/ et le déploie comme un déploiement normal.

L'image utilisée ($KIREXO_DOCS_IMAGE, kirexo-docs:latest) est celle qui aura été reconstruite entre-temps par docker:build-docs — typiquement à la suite d'une MR Renovate qui bumpe mkdocs-material ou un plugin.

Vérifier que la schedule fonctionne

  1. Aller dans Build → Pipeline schedules — la colonne Last pipeline doit afficher la date de la dernière exécution lundi 4 h UTC.
  2. Cliquer sur le statut de la pipeline → le job pages doit être vert, et lui seul (les jobs de maintenance qui filtrent sur schedule sans REBUILD_DOCS ne sont pas relancés ici).
  3. Dans les logs du job, vérifier la ligne Rebuild de la doc depuis le tag YYYYMMDDHHMM. — c'est la confirmation que git checkout --detach a réussi.
  4. Charger https://doc.kirexo.app/ (ou recharger en bypassant le cache) — le pied de page de chaque page (plugin git-revision-date-localized) reste sur la date du commit du tag, pas sur la date du build. C'est le bon comportement : on régénère le rendu, pas le contenu.

Tester immédiatement sans attendre lundi 4 h UTC

Depuis Build → Pipeline schedules, cliquer sur l'icône ▶ à droite de la schedule pour la déclencher manuellement. La pipeline démarre avec $CI_PIPELINE_SOURCE == "schedule" et REBUILD_DOCS=true, exactement comme à l'heure planifiée.

Cas d'erreur

Le job sort en 0 mais aucun rebuild n'a eu lieu

Message Aucun tag YYYYMMDDHHMM dans le repo — rien à régénérer. dans les logs. C'est le comportement attendu si la première release n'a pas encore été faite. Créez un tag de release (cf. Créer un tag de release) pour amorcer.

Le job échoue sur git checkout --detach

Cause probable : GIT_DEPTH n'est pas à 0 (shallow clone) et le tag n'est pas dans la profondeur clonée. Le job est configuré avec GIT_DEPTH: 0 — vérifier que la valeur n'a pas été surchargée au niveau projet (Settings → CI/CD → Variables) ou globalement dans .gitlab-ci.yml.

Le build mkdocs échoue en mode strict

Le contenu de la doc figée sur le tag passait pourtant la CI au moment de la release. La cause vient typiquement d'un plugin de l'image kirexo-docs plus récent qui durcit un avertissement en erreur (mode strict). Deux options :

  • corriger la doc et créer une nouvelle release (préférable — le strict mode est là pour ça) ;
  • restaurer ponctuellement la version précédente de l'image kirexo-docs (Settings → Packages and registries → Container Registry) le temps d'investiguer.

La schedule ne se déclenche jamais

Vérifier que :

  • La case Activated est cochée.
  • La variable REBUILD_DOCS=true est bien renseignée sur la schedule elle-même (et pas dans les variables CI/CD globales — sinon elle s'appliquerait aussi aux schedules de cron quotidien).
  • L'utilisateur·rice qui a créé la schedule a toujours accès au projet — GitLab désactive une schedule si son auteur·rice perd l'accès.

Voir aussi