Aller au contenu

Bootstrapper la pipeline CI

Tu installes Kirexo sur une nouvelle instance GitLab (fork, miroir, nouveau namespace) et tu veux que la pipeline CI tourne complètement : quality, tests, builds Docker, publication de la doc sur https://doc.kirexo.app/, schedule de maintenance quotidienne (Renovate, audit Composer, scan CVE, version-check d'outils).

Cette page enchaîne dans l'ordre les actions manuelles à réaliser. Chaque étape débloque la suivante — ne pas en sauter. Le détail de chaque sous-procédure est documenté ailleurs ; cette page-ci sert d'index séquentiel.

Prérequis

  • Tu as les droits Maintainer ou Owner sur le projet GitLab.
  • Tu as accès à la zone DNS de kirexo.app (registrar, panneau Cloudflare, etc.).
  • Le code Kirexo est déjà poussé sur la branche main du projet GitLab cible (la pipeline ne peut pas tourner si le repo est vide).

Prérequis : un runner tagué kirexo-self

Tous les jobs héritent de default: tags: [kirexo-self] (.gitlab-ci.yml). Sans runner en ligne portant ce tag, toute pipeline reste pending : aucun job ne se replie sur les runners hébergés par GitLab. Enregistre un runner de projet amd64, puis ajoute-lui le tag : Settings › CI/CD › Runners, éditer le runner de projet, champ Tags → ajouter kirexo-self en conservant les tags existants, sans toucher aux autres options.

La pose est à refaire si le runner est réenregistré. Sur ce projet, le runner est 53537908 ; sur une autre instance, ce sera l'identifiant de ton runner. Variante par API (attention : tag_list remplace la liste) et vérification a posteriori : Runners.

Vue d'ensemble

Étape Action Débloque
1 Réserver doc.kirexo.app dans la zone DNS Étape 4 (custom domain Pages)
2 Créer le Personal Access Token GITLAB_TOKEN Étape 3
3 Configurer la variable CI/CD GITLAB_TOKEN (masked, non protected) Étapes 4 et 5
4 Associer le domaine doc.kirexo.app à GitLab Pages Publication de la doc sur l'URL canonique
5 Créer la schedule cron 0 5 * * * sur main Audit Composer + Renovate + tools:version-check + scan CVE quotidiens
6 Bootstrap manuel : ▶ sur docker:build-base, puis build + push de kirexo-dev depuis l'hôte Tous les jobs PHP (quality:*, test:*)
7 Activer la cleanup policy du Container Registry Empêche les tags de version kirexo-prod:<x.y.z> de s'accumuler indéfiniment au fil des releases

Étape 1 — Réserver le DNS doc.kirexo.app

Préalable à toute association de custom domain côté GitLab Pages. Si l'enregistrement DNS n'existe pas, la vérification de propriété (étape 4) échoue immédiatement.

Dans le panneau DNS de ton registrar, crée un enregistrement CNAME :

Type Nom Valeur
CNAME doc <namespace>.gitlab.io. (le point final est important — shaurifr.gitlab.io. pour l'instance de référence)

Cloudflare : DNS only

Si la zone est gérée par Cloudflare, mets l'enregistrement en mode DNS only (nuage gris). Le proxy Cloudflare casserait le challenge Let's Encrypt à l'étape 4.

La propagation DNS prend de quelques minutes à 24 h selon le TTL — autant la lancer au plus tôt.

Vérifier la propagation

dig +short CNAME doc.kirexo.app
Attendu : la valeur du CNAME cible. Tant que la commande ne renvoie rien, l'étape 4 échouera.

Étape 2 — Créer le Personal Access Token GITLAB_TOKEN

Le token est utilisé par quatre jobs CI : tag:create (création de tag), security:composer-audit (MR de patch sécurité ou issue de fallback), tools:version-check (issue de retard d'outils) et dependencies:renovate (ouverture des MRs Renovate).

PAT et pas project access token

Sur GitLab.com tier gratuit, les project access tokens sont réservés à Premium/Ultimate. Le seul type de token utilisable en variable CI/CD est un Personal Access Token rattaché à un compte ayant au moins le rôle Maintainer sur le projet.

  1. Sur le compte propriétaire, aller dans User Settings → Access Tokens.
  2. Cliquer sur Add new token.
  3. Renseigner :

    Champ Valeur
    Token name kirexo-ci (ou ce que tu veux)
    Expiration date une date dans 1 an max (GitLab impose une expiration)
    Scopes api + write_repository
  4. Cliquer sur Create personal access token.

  5. Copier la valeur affichée immédiatement — GitLab ne la ré-affichera plus.

Les deux scopes sont obligatoires

  • api couvre la création d'issues et de merge requests (security:composer-audit en fallback, tools:version-check, Renovate qui ouvre les MRs).
  • write_repository couvre la création de branches et de tags : requis par security:composer-audit quand l'update résout les vulnérabilités (il pousse une branche security/composer-* puis ouvre la MR), par tag:create (création du tag de release) et par Renovate (création des branches renovate/*).

Un token porteur du seul scope api fait tourner la pipeline tant qu'aucun job ne pousse de référence. Dès que security:composer-audit tente le git push de sa branche de patch, il échoue sur 403 Forbidden si write_repository manque.

Étape 3 — Configurer la variable CI/CD GITLAB_TOKEN

  1. Dans le projet GitLab cible, aller dans Settings → CI/CD → Variables.
  2. Cliquer sur Add variable.
  3. Renseigner :

    Champ Valeur
    Type Variable
    Environments All (default)
    Visibility Masked
    Flags Protect variable décoché
    Key GITLAB_TOKEN
    Value (la valeur PAT copiée à l'étape 2)
  4. Cliquer sur Add variable.

Masked oui, Protected non

  • Mask doit être coché : sans lui, le token apparaît en clair si un job l'echo par mégarde dans son log.
  • Protect doit rester décoché : security:container-issue (+ :builders) tourne sur la pipeline de la MR / feature branch courante pour ouvrir l'issue d'alerte CVE, et Protect variable rendrait GITLAB_TOKEN indisponible sur ces refs non protégées — l'appel POST /projects/:id/issues partirait sans PRIVATE-TOKEN et retomberait en HTTP 401.

Si Mask refuse la valeur (« value does not meet the masking requirements »), regénère le PAT — sa valeur contient probablement un caractère interdit (rare avec les PATs récents).

Détail complet et liste des jobs qui consomment ce token : voir Variables CI/CD GitLab.

Les jobs security:container-issue réutilisent le même GITLAB_TOKEN

Les deux jobs d'alerting CVE conteneur (security:container-issue et security:container-issue:builders) s'authentifient via GITLAB_TOKEN (PRIVATE-TOKEN), le même PAT que celui que tu viens de configurer pour security:composer-audit, tools:version-check et Renovate. Aucune variable supplémentaire à provisionner, et aucun pré-requis Token Access à activer pour ce projet : on n'utilise pas CI_JOB_TOKEN ici parce que sa whitelist sur GitLab Free ne couvre pas POST /projects/:id/issues (retour HTTP 401 testé empiriquement). Le scope api du PAT déjà créé suffit.

Étape 4 — Configurer le custom domain GitLab Pages

L'enregistrement DNS de l'étape 1 doit avoir propagé (vérifier avec dig +short CNAME doc.kirexo.app).

Suivre la procédure complète dans Configurer le domaine GitLab Pages : déclaration du domaine, enregistrement TXT de vérification, certificat Let's Encrypt, Force HTTPS.

La première release peut attendre

GitLab Pages affiche un 404 tant que le job pages n'a pas tourné au moins une fois. C'est attendu — le bootstrap final (étape 6) ne crée pas de release ; la première vraie URL https://doc.kirexo.app/ n'apparaîtra qu'après ton premier tag (le job pages du stage release ne tourne que sur tag — cf. Créer un tag de release).

Étape 5 — Créer la schedule cron 0 5 * * * sur main

Cette unique schedule déclenche tous les jobs périodiques du stage maintenance : security:composer-audit, dependencies:renovate, tools:version-check, container_scanning (kirexo-prod), container_scanning:builders (kirexo-base, kirexo-dev) et leurs jobs d'alerting (security:container-issue, security:container-issue:builders).

Suivre la procédure dans Configurer l'audit de sécurité quotidien — schedule unique 0 5 * * * sur main, sans variable additionnelle.

Tester immédiatement

Une fois la schedule créée, clique sur l'icône ▶ à droite. La pipeline se lance avec $CI_PIPELINE_SOURCE == "schedule" exactement comme à 5 h UTC. Tu peux ainsi valider en quelques minutes que GITLAB_TOKEN a les bons scopes (sinon security:composer-audit échoue sur 403 Forbidden au git push, et Renovate sur 401 à l'ouverture de MR).

Étape 6 — Bootstrap manuel des images kirexo-base et kirexo-dev

C'est la dernière étape — et la plus facile à oublier. Sans ces deux images dans le registry, tous les jobs PHP de la pipeline standard plantent immédiatement sur ErrImagePull (l'image qu'ils consomment n'existe pas). Le commentaire en tête de .gitlab-ci.yml rappelle ce prérequis.

Les deux images ne se bootstrappent pas de la même façon :

  • docker:build-base est manuel sur main et ne dépend d'aucun job (needs: []) : son bouton ▶ reste utilisable même quand les jobs PHP échouent.
  • docker:build-dev n'a pas de bouton ▶. Il ne part sur main qu'après des stages quality et test verts, ce qui est impossible tant que kirexo-dev manque. Sa première publication se fait donc depuis l'hôte.

6.a — Publier kirexo-base depuis la CI

  1. Dans le projet GitLab, aller dans Build → Pipelines.
  2. Cliquer sur Run pipeline (en haut à droite).
  3. Branche cible : main. Pas de variable à passer. Cliquer sur Run pipeline.
  4. Sur la page de la pipeline qui démarre, repérer le stage docker. Les jobs quality:* et test:* échouent sur ErrImagePull : c'est attendu.
  5. Cliquer sur le bouton ▶ (manuel) du job docker:build-base. Attendre sa fin (vert).

6.b — Construire et pousser kirexo-dev depuis l'hôte

Dans un terminal côté hôte, à la racine du dépôt, sur un checkout à jour de main :

docker login registry.gitlab.com
docker build \
  --target frankenphp_dev \
  --build-arg BUILD_REF=$(git rev-parse --short HEAD) \
  -t registry.gitlab.com/shaurifr/kirexo/kirexo-dev:php8.5-alpine \
  .
docker push registry.gitlab.com/shaurifr/kirexo/kirexo-dev:php8.5-alpine

docker login demande ton identifiant GitLab et un Personal Access Token autorisé à écrire dans le registry. Sur une autre instance que l'instance de référence, remplace registry.gitlab.com/shaurifr/kirexo par la valeur de $CI_REGISTRY_IMAGE du projet. BUILD_REF alimente /etc/kirexo-dev.ref (cf. Image de développement kirexo-dev).

6.c — Valider

Relancer Run pipeline sur main. Les jobs PHP doivent maintenant démarrer. Si quality et test passent, docker:build-dev reconstruit l'image dans la foulée : une pipeline web évalue toujours ses changes à vrai. Cette seconde publication remplace l'image poussée depuis l'hôte par une image construite en CI.

Pourquoi pas un bouton ▶ sur docker:build-dev

Le job est automatique et sans needs pour ne jamais publier une image dev depuis un main rouge. Le détail est dans Chaînage docker:build-base → dev / prod. Les pipelines lancées par l'API (glab ci run) ne le créent pas non plus : seul Run pipeline dans l'UI (source web) déclenche une reconstruction ponctuelle.

Premier build sur base Alpine : compte un temps plus long

L'image de Kirexo est bâtie sur Alpine (cf. Pourquoi une image Alpine multi-stage). Le tout premier docker:build-base reconstruit intégralement les layers (extensions PHP via install-php-extensions, résolution des libs musl) sans cache disponible — compte une durée sensiblement plus longue à ce passage inaugural. Les builds suivants réutilisent le cache --cache-from du dernier :php8.5-alpine publié et redeviennent rapides.

Pas besoin de bootstrapper kirexo-prod ni kirexo-docs

  • kirexo-prod est construite automatiquement au premier tag de release, en amd64 par docker:build-prod et en arm64 par docker:build-prod-arm64, puis assemblée en index par docker:manifest-prod. Le runner arm64 est un runner hébergé par GitLab (saas-linux-small-arm64) : rien à enregistrer. La jambe arm64 est best-effort : si elle échoue ou ne démarre pas (quota de minutes CI épuisé), l'index ne contient que linux/amd64 et la release le signale dans sa note. Elle n'est consommée par aucun job de runner CI — uniquement par la prod via compose.prod.yaml.
  • kirexo-docs est construite automatiquement par docker:build-docs sur main (quand mkdocs/Dockerfile change) ou au tag de release, avant le job pages qui la consomme. Aucun bootstrap manuel requis.

Étape 7 — Activer la cleanup policy du Container Registry

À chaque tag de release, la pipeline publie une nouvelle image kirexo-prod:<x.y.z> et ses tags d'architecture :<x.y.z>-amd64 et, si la jambe arm64 a poussé, :<x.y.z>-arm64 (~150-300 Mo par architecture), en plus de réécrire le tag mobile :latest. Sans nettoyage, le registry accumule deux tags par release sans arm64, trois avec, sans limite. Autant configurer la politique de cleanup dès le bootstrap, avant la première release — elle s'appliquera au fur et à mesure que les tags arrivent, sans rien à modifier plus tard.

La procédure (paramètres UI exacts à saisir, choix de regex, comportement combiné Keep/Remove) est documentée séparément : Configurer la cleanup policy du registry.

Politique recommandée en résumé :

Champ Valeur
Remove tags matching (?:[0-9]+\.[0-9]+\.[0-9]+(?:-(?:amd64\|arm64))?\|[0-9]{12}) — versions sémantiques, tags d'architecture X.Y.Z-amd64 / X.Y.Z-arm64 et anciens tags horodatés. GitLab ancre le motif lui-même : pas de ^ ni de $.
Keep the most recent 30 tags per image name
Keep tags matching latest
Run cleanup Every week

Les autres images (kirexo-base, kirexo-dev, kirexo-docs) ne sont pas affectées — elles ne reçoivent aucun tag de version, et php8.5-alpine ne matche pas le motif.

Vérification finale

À ce stade :

  • [ ] dig +short CNAME doc.kirexo.app renvoie la cible GitLab Pages.
  • [ ] Settings → CI/CD → Variables affiche GITLAB_TOKEN en Masked (et pas en Protected).
  • [ ] Settings → Pages affiche doc.kirexo.app en Verified avec certificat Let's Encrypt actif et Force HTTPS coché.
  • [ ] Build → Pipeline schedules affiche la schedule Audit sécurité quotidien (ou son équivalent) activée sur main.
  • [ ] Deploy → Container Registry liste au moins kirexo-base:php8.5-alpine et kirexo-dev:php8.5-alpine.
  • [ ] Settings → Packages and registries → Container registry → Cleanup policy est Enabled avec la politique recommandée.

Une nouvelle MR pousser sur main doit maintenant déclencher une pipeline complète qui passe — toute la chaîne quality + test consomme les deux images bootstrappées à l'étape 6, l'audit Composer bloquant (quality:composer-audit) consomme le token de l'étape 3, et le rebuild de doc passera dès la prochaine release sur le domaine de l'étape 4.

Signature et SBOM : pas de variable CI/CD à provisionner

Les jobs docker:sign-prod (signature keyless cosign de kirexo-prod) et release:sbom (SBOM SPDX + CycloneDX via syft) tournent automatiquement sur la première release sans configuration supplémentaire :

  • Signature keyless : aucune clé privée à gérer. Le JWT OIDC est généré automatiquement par GitLab via id_tokens.SIGSTORE_ID_TOKEN, et Fulcio / Rekor sont des services publics. Cf. Signature keyless de kirexo-prod.
  • SBOM : syft réutilise CI_REGISTRY_USER / CI_REGISTRY_PASSWORD natifs pour scanner l'image directement dans le registry. Cf. Job release:sbom.

Signaux que tout fonctionne après la première release :

  • [ ] Build → Pipelines : docker:manifest-prod et docker:sign-prod sont passés verts sur la pipeline du tag ; la trace de docker:sign-prod affiche sept lignes ✓ signature vérifiée si docker:build-prod-arm64 est vert, cinq sinon. docker:build-prod-arm64 peut échouer (allow_failure) sans bloquer la release, qui sort alors en linux/amd64 seul.
  • [ ] Deploy → Releases : le widget Assets de la release affiche SBOM linux/amd64 en SPDX JSON et en CycloneDX JSON, plus SBOM linux/arm64 dans les deux formats si l'image arm64 a été publiée. Sans arm64, la note de release contient une section « Architecture ».

Et après ?