Pipeline GitLab CI¶
Référence factuelle de la pipeline d'intégration continue Kirexo. La configuration est éclatée entre un orchestrateur racine (.gitlab-ci.yml) et plusieurs fichiers spécialisés sous .gitlab/ci/.
Pour les procédures opérationnelles — créer un tag, configurer le domaine GitLab Pages — voir les guides correspondants :
Valider la config en local avant de pousser
Après tout changement dans .gitlab-ci.yml ou .gitlab/ci/, lancer castor ci:local : sans argument, la cible parse la config, fusionne les include / !reference / needs, valide le schéma JSON et liste tous les jobs via --list-all sans rien exécuter (ni Docker requis — marche aussi bien depuis le conteneur php que depuis l'hôte). Elle peut aussi exécuter un job précis (castor ci:local quality:phpstan), ce qui nécessite cette fois le socket Docker et donc un terminal hôte. Penser à git add tout nouveau fichier d'include avant de valider : gitlab-ci-local ne lit que les fichiers suivis par git. C'est un garde-fou de configuration — pas un substitut à la pipeline distante.
Fichiers¶
| Fichier | Rôle |
|---|---|
.gitlab-ci.yml |
Orchestrateur racine. Inclut les fichiers .gitlab/ci/*.yml, déclare les stages, le runner par défaut de tous les jobs (default: tags: [kirexo-self], cf. Runners), la workflow: (sources de pipeline acceptées, auto_cancel) et les templates .php_* réutilisés par les jobs PHP. Fixe PHP_VERSION et les noms d'images KIREXO_*_IMAGE (dont KIREXO_DOCS_IMAGE). |
.gitlab/ci/quality.yml |
Jobs qualité et tests — miroir de castor all. Stages quality (sans services, dont build:vendor qui amorce le cache Composer) et test (avec Postgres, Redis, Typesense, dont test:unit qui porte le gate de couverture). |
.gitlab/ci/docker.yml |
Build et push des cinq images kirexo-base, kirexo-dev, kirexo-prod (Dockerfile racine), kirexo-docs (mkdocs/Dockerfile) et kirexo-supply-chain (supply-chain/Dockerfile) dans le registry GitLab, plus, sur tag, la jambe arm64 de kirexo-prod (docker:build-prod-arm64), l'assemblage de son index multi-architecture (docker:manifest-prod), sa signature keyless cosign (docker:sign-prod), le test d'installation de bout en bout du bundle (docker:test-install, stage release) et le test d'installation derrière Traefik (docker:test-install-traefik, stage release). En MR qui modifie le bundle, le test d'installation sur image construite dans le job (docker:test-install-mr). |
.gitlab/ci/release.yml |
Déploiement de la documentation sur GitLab Pages, génération des SBOM (release:sbom, SPDX + CycloneDX via syft, un jeu par architecture), rendu (release:bundle-render) et publication dans le Generic Package Registry (release:bundle-publish) du bundle d'installation et des SBOM, puis création de la release GitLab avec cinq liens à permalien stable (release:create), ajout des deux liens SBOM arm64 quand l'image arm64 a été publiée (release:links-arm64), et publication du site vitrine www.kirexo.app (release:site-deploy) — déclenchés uniquement sur tag. |
.gitlab/ci/tag.yml |
Pipeline isolée qui crée un tag de version sémantique MAJEUR.MINEUR.CORRECTIF via l'API GitLab — déclenchée par la variable CREATE_TAG=true. |
.gitlab/ci/security.yml |
Scanners de sécurité natifs GitLab + gating/alerting custom : SAST Semgrep PHP, Secret Detection (secret_detection + gate bloquant security:secret-gate), Container Scanning de l'image de prod (container_scanning + security:container-issue) et des images builders (container_scanning:builders + security:container-issue:builders pour kirexo-base / kirexo-dev), et audit quotidien des dépendances Composer (security:composer-audit, ouvre une MR de patch si l'update suffit, fallback issue sinon). Inclut les templates Security/SAST.gitlab-ci.yml, Jobs/Secret-Detection.gitlab-ci.yml et Jobs/Container-Scanning.gitlab-ci.yml. |
.gitlab/ci/dependencies.yml |
Maintenance des dépendances et des outils en cron (schedule) : dependencies:renovate (montées de version automatiques) et tools:version-check (versions épinglées par ARG dans le Dockerfile). |
renovate.json (racine) |
Configuration de Renovate : managers (composer, npm, images Docker, jobs CI), regroupement des mises à jour mineures/patch, isolation des majeures, vulnerabilityAlerts, lockFileMaintenance. Voir Configurer les montées de version automatiques (Renovate). |
Stages¶
L'ordre de déclaration des stages dans .gitlab-ci.yml est l'ordre d'exécution. Au sein d'un même stage, les jobs tournent en parallèle.
| Stage | Rôle | Quand |
|---|---|---|
quality |
Amorçage du cache Composer (build:vendor, qui exécute en plus composer validate --strict --no-check-publish pour bloquer une MR qui modifie composer.json sans régénérer le lock), puis vérifications rapides sans services (style PHP, typage TypeScript, shellcheck, build mkdocs strict quality:docs-build suivi de son audit d'accessibilité quality:docs-a11y, build et contrôle du site vitrine quality:site-check, contrat de confinement quality:confinement, audit Composer bloquant). |
MR, push sur main. Sur tag de release : seul quality:composer-audit tourne (filet contre une CVE Composer publiée entre le merge et le tag). Les autres jobs de ce stage sont skippés via .rules:no-tag — leur résultat ne pourrait pas changer entre la pipeline main validée par tag:create et la pipeline du tag sur le même SHA (cf. Optimisation pipeline de tag). |
test |
Analyse statique, lint, validation schéma Doctrine, tests unitaires/intégration (avec gate de couverture porté par test:unit, échoue sous 100 %), tests Bash, E2E. |
MR, push sur main. Aucun job de ce stage ne tourne sur tag (cf. Optimisation pipeline de tag). |
docker |
Build et push des images Docker dans le registry, dont l'image de build de la doc kirexo-docs et l'image utilitaire kirexo-supply-chain (cosign + syft). |
Images du Dockerfile racine : docker:build-base manuel sur main (hors schedule) et en MR ; docker:build-dev automatique sur main quand l'image dev change, absent en MR ; docker:build-prod automatique en MR sur fichiers déclencheurs, manuel sinon en MR, jamais sur main. Les trois sont automatiques sur tag de release, et aucune n'est construite en schedule. docker:build-prod-arm64, docker:manifest-prod et docker:sign-prod : tag de release uniquement. docker:build-docs et docker:build-supply-chain : automatique sur main si le Dockerfile correspondant change (manuel sinon), manuel sur MR, automatique sur tag de release. docker:test-install-mr : automatique et bloquant en MR qui modifie install/compose.yaml ou install/.env.example, absent ailleurs. |
release |
Déploiement GitLab Pages (via l'image kirexo-docs), SBOM, rendu, tests d'installation (docker:test-install, docker:test-install-traefik) et publication du bundle d'installation, release GitLab avec changelog, publication du site vitrine (release:site-deploy). |
Tag de release de version sémantique MAJEUR.MINEUR.CORRECTIF ou schedule hebdo avec REBUILD_DOCS=true pour pages (rebuild de la doc figée sur le dernier tag — cf. Job pages). |
maintenance |
Jobs périodiques et non bloquants : SAST informatif (semgrep-sast, sur chaque MR et chaque push main), audit Composer quotidien (security:composer-audit — tente d'ouvrir une MR de patch, fallback issue), Renovate (dependencies:renovate), contrôle des outils épinglés (tools:version-check), scan CVE de l'image kirexo-prod (container_scanning, en cron quotidien ET sur tag de release), scan CVE des images builders (container_scanning:builders sur kirexo-base et kirexo-dev, cron quotidien uniquement) et ouverture d'issue sur CVE conteneur (security:container-issue + security:container-issue:builders). Le garde-fou de sécurité bloquant reste quality:composer-audit, dans le stage quality. |
MR + push main pour le SAST ; schedule quotidien pour les jobs de maintenance ; tag de release pour container_scanning + security:container-issue (scan de l'image fraîchement poussée). |
tag |
Création d'un tag de version sémantique via l'API GitLab. | CREATE_TAG=true et depuis la branche main uniquement. |
Sources de pipeline acceptées¶
La clause workflow:rules filtre les déclenchements à la racine — toute pipeline qui n'entre pas dans cette liste n'est même pas créée :
| Source | Condition | Effet |
|---|---|---|
| Merge Request | $CI_PIPELINE_SOURCE == "merge_request_event" |
Pipeline complète quality + test sur chaque push de MR. |
Push sur main |
$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH |
Pipeline complète quality + test à chaque commit poussé sur main. |
| Tag de release | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ |
quality:composer-audit (seul rescapé des stages quality/test — cf. Optimisation pipeline de tag) + docker (auto, dont docker:build-docs) + release (Pages + release GitLab) + scan/issue CVE de l'image fraîchement poussée. Seul le format de version sémantique MAJEUR.MINEUR.CORRECTIF (ex. 0.0.1, sans préfixe v) déclenche la pipeline : les anciens tags horodatés YYYYMMDDHHMM et tout tag annexe (v1.0, wip-foo, etape4-*) ne créent AUCUNE pipeline — pas de release, pas de build d'images, pas de redéploiement Pages. La même clause, écrite non quotée et identique au caractère près, est répétée sur tous les jobs de release (.rules:standard, .rules:ts-check, .rules:docker, docker:build-prod-arm64, docker:manifest-prod, docker:sign-prod, docker:test-install, docker:test-install-traefik, pages, release:sbom, release:bundle-render, release:bundle-publish, release:create, release:links-arm64, release:site-deploy, docker:build-docs, container_scanning, security:container-issue) pour rester cohérente avec ce filtre racine ; le garde-fou versionné tests/Unit/Infra/GitlabCiRulesGuardrailsTest.php compare ces clauses à la forme attendue. |
| Création de tag | $CREATE_TAG == "true" (uniquement depuis main) |
Pipeline isolée stage tag uniquement — ne joue rien d'autre. La rule du job tag:create exige en plus $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH : déclencher CREATE_TAG=true depuis une feature branch ne crée pas de tag. Le job refuse aussi de taguer si aucune pipeline success n'existe pour le commit ciblé, sauf FORCE_TAG=true (cf. Pipeline de création de tag). |
| Schedule | $CI_PIPELINE_SOURCE == "schedule" |
Les jobs de maintenance du stage maintenance : security:composer-audit (audit Composer + tentative de MR de patch), dependencies:renovate (montées de version), tools:version-check (versions d'outils épinglées), container_scanning (scan CVE de kirexo-prod:latest), container_scanning:builders (matrix sur kirexo-base et kirexo-dev:php$PHP_VERSION) et les jobs d'alerting security:container-issue / security:container-issue:builders (ouvrent une issue par image vulnérable). Un seul schedule quotidien suffit à les déclencher tous (cf. stage maintenance). Une seconde schedule hebdo, distincte (variable REBUILD_DOCS=true), réveille le job pages du stage release pour rafraîchir le rendu de la doc sans attendre la prochaine release (cf. Job pages). Aucune image du Dockerfile racine n'est construite en schedule : docker:build-base, docker:build-dev et docker:build-prod sont absents de ces pipelines. |
Le bloc workflow:auto_cancel (.gitlab-ci.yml) porte deux directives complémentaires :
| Directive | Valeur | Effet |
|---|---|---|
on_new_commit |
interruptible |
Annule automatiquement toute pipeline interruptible: true en cours dès qu'un nouveau commit est poussé sur la même branche — économise du runner sur les MRs où plusieurs corrections s'enchaînent. |
on_job_failure |
all |
Dès qu'un job échoue, annule tous les jobs encore en cours de la pipeline. Sans elle, seuls les jobs en aval via needs: étaient bloqués ; les jobs parallèles du même stage continuaient inutilement jusqu'à leur terme. Avec elle, le premier échec arrête toute la pipeline — feedback plus rapide, runner libéré au plus tôt. |
Les jobs docker:* (dont docker:build-docs), release:*, pages, tag:create, dependencies:renovate et tools:version-check sont explicitement interruptible: false (un build d'image, une création de tag ou une ouverture de MRs de montée de version ne doit jamais être interrompu à mi-parcours) — interruptible: false les protège aussi de l'annulation déclenchée par on_job_failure: all. Seule exception parmi les docker:* : docker:test-install-mr, interruptible: true, qui ne pousse rien et n'a plus d'objet dès qu'un nouveau commit arrive sur la MR.
Runners¶
Le bloc default: de .gitlab-ci.yml fixe le runner de tous les jobs :
| Runner | Architecture | Tag | Jobs |
|---|---|---|---|
Runner de projet du mainteneur (53537908) |
amd64 | kirexo-self |
Tous les jobs, par héritage de default |
| Runner hébergé par GitLab | arm64 | saas-linux-small-arm64 |
docker:build-prod-arm64 seul (.gitlab/ci/docker.yml) |
Les runners d'instance GitLab restent activés sur le projet, mais aucun ne porte le tag kirexo-self : un job qui hérite du défaut ne peut pas y partir, et ne consomme donc pas le quota de minutes CI du plan (#335).
Le tags: d'un job remplace le défaut, sans fusion. docker:build-prod-arm64 déclare tags: [saas-linux-small-arm64] : il ne porte que ce tag, pas kirexo-self. C'est la seule exception — le mainteneur n'a pas de runner arm64 natif.
Runner hors ligne ⇒ jobs pending, sans repli. Si le runner kirexo-self est arrêté ou déconnecté, les jobs de toutes les pipelines (MR, main, tag, CREATE_TAG, schedules) restent en attente. Aucun ne bascule sur un runner hébergé : un repli silencieux rouvrirait la consommation de quota.
Pose du tag. Le tag est porté par le runner côté GitLab, pas par le dépôt. Pour ce projet, le runner est 53537908. La pose est à refaire si le runner est réenregistré : le nouvel enregistrement n'a pas de tag. Deux voies équivalentes :
- Interface : Settings › CI/CD › Runners, éditer le runner de projet, champ Tags : ajouter
kirexo-selfen conservant les tags existants. Ne modifier aucune autre option. -
API (rôle Maintainer ou plus) :
PUT /api/v4/runners/:idremplacetag_list, il ne fusionne pas. Lire d'abord la liste existante, puis renvoyer cette liste complétée :RUNNER_ID=53537908 # 1. Tags actuels curl --silent --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ "https://gitlab.com/api/v4/runners/$RUNNER_ID" | jq '.tag_list' # 2. Liste existante + kirexo-self (ici, liste vide au départ) curl --silent --request PUT --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ --header "Content-Type: application/json" \ --data '{"tag_list": ["kirexo-self"]}' \ "https://gitlab.com/api/v4/runners/$RUNNER_ID" | jq '.tag_list'Si l'étape 1 renvoie par exemple
["docker"], envoyer{"tag_list": ["docker", "kirexo-self"]}.
Vérification a posteriori. Dans une pipeline, chaque job sauf docker:build-prod-arm64 doit avoir tourné sur le runner du mainteneur, c'est-à-dire un runner non partagé :
curl --silent --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
"https://gitlab.com/api/v4/projects/<projet>/pipelines/<pipeline_id>/jobs?per_page=100" \
| jq -r '.[] | select(.runner != null and .name != "docker:build-prod-arm64" and .runner.is_shared != false) | .name'
<projet> est l'identifiant numérique du projet ou son chemin encodé (shaurifr%2Fkirexo). Une sortie vide signifie que la pipeline est conforme. Les jobs sans runner (pas encore démarrés, ignorés) sont exclus du filtre.
Garde-fou M8. tests/Unit/Infra/GitlabCiMultiArchGuardrailsTest.php contrôle .gitlab-ci.yml et les fichiers .gitlab/ci/*.yml qu'il inclut :
default.tagsvaut exactement[kirexo-self]dans.gitlab-ci.yml;- aucun fichier inclus ne déclare son propre
default:; - tout fichier inclus localement fait partie du corpus lu (pas d'angle mort) ;
- aucun job ni gabarit caché (
.docker_job,.php_*_job…), horsdocker:build-prod-arm64, ne sort du défaut : pas detags:différent de[kirexo-self](ni sous forme!reference), pas deinherit: default:qui excluttags, pas d'extends: docker:build-prod-arm64; - le nombre de jobs inspectés dépasse un plancher (anti-vacuité).
Règles réutilisables (.rules:*)¶
Plutôt que de répéter le bloc rules: dans chaque job, la CI définit des hidden jobs réutilisables. Les jobs concernés y font référence via la syntaxe !reference [.rules:NAME, rules], que GitLab aplatit dans leur propre rules: à la compilation. Une seule définition à maintenir, comportement identique partout.
Huit sont déclarés dans l'orchestrateur .gitlab-ci.yml. Sept d'entre eux couvrent les stages quality et test et sont détaillés ci-dessous ; le huitième, .rules:docker, est décrit avec les jobs de build.
Un neuvième, .rules:code-scan, vit dans .gitlab/ci/security.yml avec les jobs qu'il sert : il porte les scanners de code (secret_detection, container_scanning) sur MR et sur main, jamais sur une pipeline CREATE_TAG=true — le code y a déjà été scanné en MR. Il est déclaré au plus près de ses consommateurs plutôt que dans l'orchestrateur, comme le reste de la configuration de sécurité.
| Hidden job | Périmètre | Filtre MR | Comportement sur main et tag |
|---|---|---|---|
.rules:standard |
Jobs quality / test qui doivent tourner aussi sur tag — aujourd'hui réservé à quality:composer-audit (filet CVE entre merge et tag). |
Aucun filtre changes: — tourne sur toute MR. |
Tourne toujours, y compris sur tag (hors pipeline CREATE_TAG=true). |
.rules:no-tag |
Jobs quality / test dont le résultat ne peut pas changer entre la pipeline main validée par tag:create et la pipeline du tag sur le même SHA : quality:cs-fix, quality:shellcheck, quality:confinement, quality:docs-build, quality:docs-a11y, quality:site-check, quality:phpstan, quality:lint. Même filtre MR que .rules:standard mais sans la branche tag (cf. Optimisation pipeline de tag). |
Aucun filtre changes: — tourne sur toute MR. |
Tourne sur main (hors CREATE_TAG=true). Ne tourne pas sur tag. |
.rules:tests-unit-no-tag |
test:unit seul. |
Allowlist changes: propre à la suite — voir Allowlists changes: des suites de tests. |
Tourne sur main (hors CREATE_TAG=true). Ne tourne pas sur tag. |
.rules:tests-bash-no-tag |
test:bash seul. |
Allowlist changes: propre à la suite — voir Allowlists changes: des suites de tests. |
Tourne sur main (hors CREATE_TAG=true). Ne tourne pas sur tag. |
.rules:tests-e2e-no-tag |
test:e2e seul. |
Allowlist changes: propre à la suite — voir Allowlists changes: des suites de tests. |
Tourne sur main (hors CREATE_TAG=true). Ne tourne pas sur tag. |
.rules:ts-check |
Réservé — plus aucun job ne l'utilise depuis la migration vers .rules:ts-check-no-tag. |
Allowlist changes: sur les sources TypeScript et leurs déclencheurs. |
Tourne sur main et sur tag. |
.rules:ts-check-no-tag |
quality:ts-check. Même allowlist que .rules:ts-check (partagée via YAML anchor). |
Allowlist changes: sur les sources TypeScript et leurs déclencheurs (package.json, tsconfig.json, **/*.ts, **/*.tsx, Dockerfile, CI — où « CI » = .gitlab-ci.yml + .gitlab/ci/quality.yml, pas tout .gitlab/ci/). |
Tourne sur main (hors CREATE_TAG=true). Ne tourne pas sur tag. |
Conséquence pratique : sur une MR qui ne touche que la doc ou des fichiers de cadrage, la pipeline reste verte rapidement (les jobs de test PHP / TS ne tournent même pas). Sur main, le filet est complet — pas de skip silencieux d'un test au merge. Sur tag, seul quality:composer-audit rejoue le filet de sécurité ; les jobs déjà validés sur main (style, analyse statique, tests) sont skippés pour ne pas dépenser de minutes runner inutilement.
Allowlists changes: des suites de tests¶
GitLab ne sait pas faire « tout sauf X » dans rules:changes: — il faut lister ce qui doit déclencher les tests. Chaque suite porte sa propre liste : test:unit, test:bash et test:e2e se déclenchent indépendamment les uns des autres. Les trois listes vivent dans .gitlab-ci.yml, chacune juste au-dessus du hidden job qu'elle sert. Le raisonnement qui a conduit à ce découpage — et le contresens à ne pas y voir — est dans Le coût réel d'une pipeline CI.
✓ = le chemin figure dans la liste de cette suite ; une MR qui le modifie déclenche le job.
| Chemin / fichier | test:unit |
test:bash |
test:e2e |
Pourquoi |
|---|---|---|---|---|
src/**/* |
✓ | — | ✓ | Le code de production. |
config/**/*, migrations/**/* |
✓ | — | ✓ | Configuration Symfony et schéma : changent le comportement à l'exécution comme le rendu des pages. |
templates/**/* |
✓ | — | ✓ | Les tests d'intégration rendent du Twig ; les E2E le chargent dans un navigateur. |
assets/**/* |
✓ | — | ✓ | Côté test:unit, tests/Unit/Assets/SelfHostedFontsConsistencyTest.php lit assets/fonts et assets/styles/*.css ; côté E2E, ce sont les assets réellement servis. |
public/**/* |
— | — | ✓ | Servi tel quel au navigateur. |
importmap.php |
✓ | — | ✓ | Cartographie des modules JS chargés par les pages. |
bin/**/* |
✓ | — | ✓ | Le before_script de .php_e2e_job migre et charge les fixtures via bin/console. |
castor.php, castor/**/* |
✓ | — | — | Le PHP de Castor est couvert par tests/Unit/Castor/. Absent de la liste bats : aucun .bats ne source de Castor. |
infra/**/* |
✓ | ✓ | — | Les bats sourcent les libs shell d'infra/ ; côté test:unit, tests/Unit/Castor/Firewall/FirewallRegexConsistencyTest.php source infra/egress/allowlist.lib.sh et compare la regex bash à son équivalent PHP — c'est le seul job qui voit une divergence entre les deux. |
tests/*.php |
✓ | — | — | tests/bootstrap.php prépare la base de test. Volontairement absent de la liste E2E, bien que phpunit.dist.xml l'utilise pour toutes les suites : le bootstrap est agnostique de la suite, donc une casse rougit déjà test:unit. |
tests/Unit/**/*, tests/Integration/**/* |
✓ | — | — | Les suites exécutées par le job. |
tests/Bash/**/* |
— | ✓ | — | La suite exécutée par le job. |
tests/E2E/**/* |
— | — | ✓ | La suite exécutée par le job. |
.claude/hooks/**/*, .claude/skills/*/bin/*, .claude/*.tpl |
— | ✓ | — | Les trois familles de .claude/ réellement couvertes par des bats : tests/Bash/stop-decision/, tests/Bash/session-dir/, tests/Bash/detect-twig/, tests/Bash/demo-video/ et tests/Bash/worktree/wt_render_settings_local.bats, qui asserte sur le contenu versionné de .claude/settings.local.json.tpl. |
phpunit.dist.xml |
✓ | — | ✓ | Configuration des suites PHPUnit. |
phpstan.dist.neon, .php-cs-fixer.dist.php |
✓ | — | — | Configuration des outils qualité : un changement peut faire bouger le résultat des suites unit + integration. |
.gitlab/ci/docker.yml, .gitlab/ci/release.yml, .gitlab/ci/security.yml |
✓ | — | — | Lus par les gardes versionnées de tests/Unit/Infra/ (règles de docker:build-prod, jobs multi-architecture, needs sur docker:manifest-prod de release:sbom, release:bundle-render, release:bundle-publish, release:create, release:links-arm64 et container_scanning). Une MR qui ne modifie que l'un de ces fichiers rejoue les gardes qui le contrôlent. |
À quoi s'ajoute un bloc « environnement » de neuf entrées, présent dans les trois listes :
| Chemin / fichier | Pourquoi |
|---|---|
composer.json, composer.lock |
Changement de dépendances → re-tester. |
.gitlab-ci.yml, .gitlab/ci/quality.yml |
Les deux seuls fichiers CI qui peuvent changer le résultat des tests : .gitlab-ci.yml porte les templates .php_*_job (images, services, variables d'environnement), .gitlab/ci/quality.yml porte les jobs test:* eux-mêmes (script phpunit). On ne surveille pas .gitlab/ci/**/* en bloc — release.yml, docker.yml, security.yml, dependencies.yml et tag.yml n'ont aucun impact sur l'exécution des tests, les inclure dans ce bloc relancerait les trois suites quand on ne touche qu'au déploiement. docker.yml, release.yml et security.yml figurent en revanche, hors de ce bloc, dans la seule liste de test:unit, dont les gardes les lisent (cf. tableau ci-dessus). |
Dockerfile, .dockerignore, compose*.yaml |
Changement d'environnement d'exécution. |
.env, .env.test |
Variables d'environnement effectives en CI. |
La duplication de ce bloc est assumée
YAML ne sait pas concaténer deux séquences, et !reference ne s'applique pas à changes: — seule la clé rules: d'un hidden job est référençable. Les neuf entrées sont donc recopiées à l'identique dans les trois listes. Ce n'est pas le YAML qui tient leur cohérence, c'est le garde-fou versionné décrit ci-dessous.
À l'inverse, le périmètre considéré comme doc-only — donc skippé sur MR par les trois listes — est : docs/**, mkdocs.yml, mkdocs/**, Étapes/**, README.md, CLAUDE.md, apprentissage.md, et le reste de .claude/** (agents, SKILL.md, réglages) hors des trois familles listées plus haut. Une MR qui ne touche que ces fichiers ne lance ni test:unit, ni test:bash, ni test:e2e.
changes: raisonne au fichier, pas à la ligne
Les allowlists ne surveillent que .gitlab-ci.yml et .gitlab/ci/quality.yml côté CI, mais le filtre changes: ne distingue pas quoi a changé dans un fichier listé : modifier un simple commentaire dans .gitlab-ci.yml relance quand même les trois suites, puisque ce fichier appartient aux trois blocs « environnement ». Faux positif assumé — c'est le filet « un changement d'un template de test = re-test », préférable au risque de rater une vraie modification de l'environnement d'exécution.
Tout nouveau dossier de prod doit être couvert par au moins une liste
Les allowlists sont exhaustives : si on crée un nouveau dossier de prod (ex. app/, lib/, plugins/) et qu'on oublie de l'ajouter à au moins une des trois listes de .gitlab-ci.yml, ses changements ne déclencheront aucun test sur MR. Le filet ne tombera qu'au moment du merge sur main (où les tests tournent toujours) — trop tard pour un feedback de review, et d'autant plus tard que les MRs de lot mergent vers la branche parente d'étape, pas vers main.
C'est précisément ce que vérifie le garde-fou versionné de tests/Unit/Infra/ : il lit .gitlab-ci.yml et fait rougir la CI si un dossier de production n'est couvert par aucune des trois listes. Le réflexe reste d'éditer .gitlab-ci.yml dans la même MR que la création du dossier — le garde-fou est le filet, pas la procédure.
Optimisation pipeline de tag¶
La pipeline déclenchée par un tag de version semver ne rejoue ni les vérifications de qualité, ni les tests, ni le build du cache vendor : ces jobs ont déjà tourné sur le même SHA dans la pipeline main qui a précédé le tag, et tag:create (cf. Pipeline de création de tag) refuse explicitement de poser le tag si aucune pipeline success n'existe pour ce commit. Rejouer ces jobs serait donc de la duplication pure — même code, même résultat.
Concrètement, sur tag, les jobs suivants sont skippés via les variantes -no-tag de leurs .rules: :
| Job | Rule appliquée | Pourquoi skippé sur tag |
|---|---|---|
quality:cs-fix |
.rules:no-tag |
Style PHP — résultat invariant sur le même SHA. |
quality:ts-check |
.rules:ts-check-no-tag |
Typage TypeScript — idem. |
quality:shellcheck |
.rules:no-tag |
Lint shell — idem. |
quality:confinement |
.rules:no-tag |
Contrat de confinement — ne lit que des fichiers versionnés, donc résultat invariant sur le même SHA. |
quality:docs-build |
.rules:no-tag |
Build mkdocs strict — déjà validé en MR via preview ; le déploiement réel est porté par pages sur tag. |
quality:docs-a11y |
.rules:no-tag |
Audit d'accessibilité de la doc — même règle que quality:docs-build, dont il consomme l'artefact : il serait sinon créé dans une pipeline où son needs est absent. |
quality:site-check |
.rules:no-tag |
Build et contrôle du site vitrine — déjà validés en MR via preview ; sur tag, release:site-deploy reconstruit et revérifie le site avant de le publier. |
quality:phpstan |
.rules:no-tag |
Analyse statique — idem. |
quality:lint |
.rules:no-tag |
Lint Twig/YAML/conteneur + doctrine:schema:validate — idem. |
test:unit |
.rules:tests-unit-no-tag |
Tests unitaires + gate de couverture — idem. |
test:bash |
.rules:tests-bash-no-tag |
Tests bats — idem. |
test:e2e |
.rules:tests-e2e-no-tag |
Tests E2E Panther — idem. |
build:vendor |
rules custom sans branche tag |
Cache Composer reproductible depuis composer.lock — les jobs docker:* rebuilent leur propre vendor/ à partir du même lockfile pour produire l'image, ils n'ont pas besoin du cache. |
Seuls les jobs qui produisent un livrable ou dont le résultat dépend de l'instant T du tag continuent de tourner :
quality:composer-audit(.rules:standard, branche tag conservée) — filet de sécurité : une CVE Composer peut être publiée entre le merge surmainet la création du tag ; on ne veut pas qu'un audit silencieusement obsolète passe en prod ;docker:build-base,docker:build-dev,docker:build-prod,docker:build-prod-arm64,docker:build-docs,docker:build-supply-chain— production des images du tag ;docker:build-prod-arm64est best-effort (allow_failure: true) : son échec ne bloque pas la release, qui sort alors enlinux/amd64seul ;docker:manifest-prod— assemblage de l'indexkirexo-prod(linux/amd64, pluslinux/arm64si la jambe arm64 a réussi) ;docker:sign-prod— signature keyless de cet index ;docker:test-install— test d'installation de bout en bout du bundle rendu, avant sa publication ;docker:test-install-traefik— installation du bundle rendu derrière un vrai Traefik, avant sa publication ;pages,release:sbom,release:bundle-render,release:bundle-publish,release:create,release:links-arm64— déploiement de la doc, SBOM, bundle d'installation publié en paquet, release GitLab et ses liens SBOM arm64 conditionnels ;release:site-deploy— build, contrôle et publication du site vitrine à la version du tag ;container_scanning+security:container-issue— scan CVE de l'imagekirexo-prod:$CI_COMMIT_TAGau moment de la release (cf. Jobscontainer_scanningetsecurity:container-issue).
Gain typique : une douzaine de jobs supprimés sur chaque pipeline de tag, qui représentaient l'essentiel des minutes runner consommées par la pipeline de release. La validation de qualité reste pleine et entière sur main — elle ne diminue pas, elle se déplace au seul endroit où elle apporte un signal.
Graphe de dépendances (needs:)¶
Les jobs des stages quality et test ne s'exécutent pas en cascade stage-par-stage : un DAG needs: les fait démarrer dès que leur dépendance directe est verte, sans attendre la fin du stage précédent. Gain de vitesse sur chaque pipeline.
| Job | Stage | needs: |
Démarre quand |
|---|---|---|---|
build:vendor |
quality |
[] (détaché) |
Début de pipeline — amorce le cache vendor/ (cf. Cache Composer). |
quality:cs-fix |
quality |
build:vendor |
Dès que vendor/ est en cache. |
quality:ts-check |
quality |
— | Début de pipeline. |
quality:shellcheck |
quality |
— | Début de pipeline. |
quality:confinement |
quality |
[] (détaché) |
Début de pipeline. |
quality:docs-build |
quality |
[] (détaché) |
Début de pipeline. |
quality:docs-a11y |
quality |
quality:docs-build (artefact) |
Dès que le build mkdocs strict passe — needs intra-stage, avec artifacts: true. |
quality:site-check |
quality |
[] (détaché) |
Début de pipeline. |
quality:composer-audit |
quality |
[] (détaché) |
Début de pipeline. |
quality:phpstan |
test |
quality:cs-fix |
Dès que le style passe. |
quality:lint |
test |
quality:cs-fix |
Dès que le style passe. |
test:unit |
test |
quality:cs-fix |
Dès que le style passe. |
test:e2e |
test |
quality:cs-fix |
Dès que le style passe. |
test:bash |
test |
quality:shellcheck |
Dès que le lint shell passe. |
Conséquence : build:vendor est en tête de la chaîne PHP — tous les jobs PHP descendent de lui par needs et lisent le cache vendor/ qu'il a poussé, au lieu de le télécharger chacun en parallèle (cf. Cache Composer). Si quality:cs-fix échoue, les jobs PHP du stage test ne tournent pas (économie de runner) ; inutile d'analyser du code dont le style est déjà cassé. test:bash ne dépend que de quality:shellcheck — pas la peine de tester des fonctions bash qui ne passent même pas shellcheck. La métrique de couverture est portée par test:unit seul (cf. Tests et gate de couverture).
Job quality:composer-audit¶
Audit bloquant des vulnérabilités connues de composer.lock, sur chaque MR, main et tag. C'est le vrai garde-fou de sécurité de la pipeline — il vit dans le stage quality, en tête (needs: []), pas dans le stage maintenance. Complémentaire de security:composer-audit (cron quotidien du stage maintenance, ouvre une issue) : ici, une dépendance vulnérable bloque le merge — feedback immédiat au moment du changement.
| Caractéristique | Valeur |
|---|---|
| Stage | quality |
| Image | KIREXO_BASE_IMAGE (binaire composer disponible). |
needs: |
[] — détaché du DAG, démarre dès le début de pipeline. |
| Commande | composer audit --no-interaction --locked — audite composer.lock sans installer vendor/, donc très rapide (pas de composer install). |
| Déclencheurs | MR, main (hors CREATE_TAG=true), tag (.rules:standard). |
| Effet en cas de vulnérabilité | Le job échoue → la MR ne peut pas être mergée tant que la dépendance n'est pas mise à jour. |
Job quality:docs-build¶
Build mkdocs en mode strict avec exposition d'une preview dans la MR. Sert à détecter dès la MR les liens cassés, snippets manquants et avertissements de plugin qui, sans ce job, ne sortiraient qu'au job pages (déclenché uniquement sur tag de release) — c'est-à-dire trop tard. La preview permet en plus de review visuellement le rendu avant merge.
| Caractéristique | Valeur |
|---|---|
| Stage | quality |
| Image | $KIREXO_DOCS_IMAGE (mkdocs-material + plugins déjà installés ; entrypoint: [""] pour neutraliser l'entrypoint mkdocs hérité de l'image et laisser GitLab CI exécuter le script via le shell). |
needs: |
[] — détaché du DAG, démarre dès le début de pipeline. |
GIT_DEPTH |
0 (histoire git complète pour git-revision-date-localized, sinon dégradation silencieuse sur la date des pages). |
| Commande | mkdocs build --strict -d public |
| Artifact | public/ — conservé 1 semaine (expire_in: 1 week). Exposé via expose_as: "Documentation preview" : GitLab affiche un bouton « View exposed artifact » dans la sidebar du widget de la MR qui ouvre directement public/index.html, sans télécharger l'archive. |
| Déclencheurs | .rules:no-tag — MR, main (hors CREATE_TAG=true). Ne tourne pas sur tag. |
| Job aval | quality:docs-a11y audite l'artefact public/. |
Le rendu produit par pages (sur tag de release) repose sur la même image kirexo-docs : un build qui passe ici passe également au déploiement. La preview MR est jetable (1 semaine) — la version « officielle » reste celle servie par GitLab Pages sur le dernier tag (cf. Job pages).
Pourquoi expire_in: 1 week
expose_as exige un artifact accessible directement (ici public/index.html). Sans expiration, ces previews s'accumuleraient (une par MR × N pushs). Une semaine est largement suffisant pour la durée de vie d'une review.
Job quality:docs-a11y¶
Audit d'accessibilité automatisé de la doc construite par quality:docs-build. @axe-core/cli contrôle l'accueil et une page de chaque quadrant Diátaxis, en thème clair puis en thème sombre, sur les règles WCAG 2.0 et 2.1 de niveaux A et AA. Une seule violation fait échouer le job.
| Caractéristique | Valeur |
|---|---|
| Fichier | .gitlab/ci/quality.yml |
| Stage | quality |
| Image | $KIREXO_DEV_IMAGE (Chromium, chromedriver, Node et php déjà présents). |
needs: |
quality:docs-build avec artifacts: true : le job récupère l'artefact public/ et démarre dès la fin du build. |
timeout |
10m |
| Variables | CHROMEDRIVER_SKIP_DOWNLOAD: "true" (le paquet npm chromedriver, dépendance d'@axe-core/cli, ne télécharge pas son binaire : c'est celui de l'image qui sert) ; DOCS_A11Y_BASE_URL: http://127.0.0.1:8000 ; DOCS_A11Y_PAGES (pages auditées, cf. ci-dessous) ; DOCS_A11Y_DARK_FLAG: force-dark-mode (drapeau Chromium du thème sombre). |
| Outil | npx --yes -p "@axe-core/cli@<contrainte>" axe. La contrainte est lue dans les devDependencies de package.json : le projet n'a ni node_modules ni lockfile npm, comme pour castor ts:check. Si elle est absente, le job s'arrête sur @axe-core/cli absent des devDependencies de package.json. |
| Tags axe | wcag2a,wcag2aa,wcag21a,wcag21aa |
| Artifacts | var/axe-docs/ (un rapport JSON par thème) et var/log/docs-a11y-server.log, avec when: always et expire_in: 1 week. |
| Déclencheurs | .rules:no-tag — MR, main (hors CREATE_TAG=true). Ne tourne pas sur tag. |
retry |
Aucun : une violation doit rester rouge, et workflow:auto_cancel:on_job_failure: all annule le reste de la pipeline. |
interruptible |
true. |
Pages auditées¶
| Quadrant | URL auditée | Fichier attendu dans l'artefact |
|---|---|---|
| Accueil | http://127.0.0.1:8000/ |
public/index.html |
| Tutorials | http://127.0.0.1:8000/tutorials/installer-kirexo-chez-soi/ |
public/tutorials/installer-kirexo-chez-soi/index.html |
| Tutorials | http://127.0.0.1:8000/tutorials/ecrire-un-plugin/ |
public/tutorials/ecrire-un-plugin/index.html |
| How-to | http://127.0.0.1:8000/how-to/installer-un-plugin/ |
public/how-to/installer-un-plugin/index.html |
| Reference | http://127.0.0.1:8000/reference/contrat-plugin/ |
public/reference/contrat-plugin/index.html |
| Explanation | http://127.0.0.1:8000/explanation/architecture-plugins/ |
public/explanation/architecture-plugins/index.html |
Les cinq pages hors accueil (le tutoriel d'installation et une page par quadrant) sont codées en dur dans la variable DOCS_A11Y_PAGES. Avant tout audit, une garde vérifie que chacun des six fichiers existe dans l'artefact. Renommer ou déplacer une de ces pages (docs/tutorials/installer-kirexo-chez-soi.md, docs/tutorials/ecrire-un-plugin.md, docs/how-to/installer-un-plugin.md, docs/reference/contrat-plugin.md, docs/explanation/architecture-plugins.md) fait donc échouer le job avec un message qui nomme le fichier manquant :
Sans cette garde, le serveur intégré de PHP remonterait vers un index.html parent et axe auditerait une autre page sans le signaler. Le correctif consiste à mettre à jour DOCS_A11Y_PAGES dans .gitlab/ci/quality.yml, dans la même MR que le renommage.
Déroulé¶
- Garde sur l'artefact, décrite ci-dessus.
- Neutralisation de
public/index.php. Le checkout du job contient lepublic/de Symfony, et l'artefact dequality:docs-buildse dépose par-dessus. Pour une URL de répertoire, le serveur intégré de PHP sertindex.phpavantindex.html: sans précaution,GET /exécuterait le front controller Symfony, sansvendor/, et axe auditerait une page d'erreur 500. Le job lance doncrm -f public/index.php. Le workspace CI est jetable, et la doc ne contient aucun fichier.php. - Serveur HTTP local :
php -S 127.0.0.1:8000 -t publicen arrière-plan, journal dansvar/log/docs-a11y-server.log. Uncurl --retry 10 --retry-connrefusedattend qu'il réponde. Un serveur plutôt que des URLfile://: les URL de répertoire et les chemins relatifs de Material n'ont de sens que derrière un serveur qui résoutindex.html. - Une passe par thème (
clair, puissombre) : sonde du thème, puis audit axe des six URL.
Bascule clair / sombre et sonde par l'effet¶
@axe-core/cli ne sait ni injecter de script ni écrire dans localStorage. Le job émule donc la préférence système dans Chromium. Le script anti-flash de la doc (mkdocs/overrides/main.html) la lit quand la clé kirexo-theme est absente, ce qui est le cas d'un profil Chromium neuf. C'est le même mécanisme que castor site:check (castor/src/Site/AccessibilityChecker.php).
| Thème | Drapeau ajouté aux options Chrome | data-theme attendu sur <html> |
Rapport |
|---|---|---|---|
| clair | aucun | light |
var/axe-docs/docs-a11y-clair.json |
| sombre | force-dark-mode (DOCS_A11Y_DARK_FLAG) |
dark |
var/axe-docs/docs-a11y-sombre.json |
Les options Chrome de base sont celles d'AccessibilityChecker::chromeArguments() : no-sandbox,disable-dev-shm-usage,disable-gpu,no-proxy-server. axe pilote /usr/bin/chromium par /usr/bin/chromedriver, tous deux fournis par l'image.
Avant chaque passe, une sonde lance /usr/bin/chromium --headless=new … --dump-dom sur l'accueil, avec le drapeau du thème, et cherche data-theme="light" ou data-theme="dark" sur la balise <html>. Si le thème attendu n'est pas appliqué, le job s'arrête avant axe (échec fermé) :
Thème sombre non appliqué par Chromium (attendu data-theme="dark" sur <html>) — l'audit axe serait trompeur ; vérifier l'anti-flash de la doc ou DOCS_A11Y_DARK_FLAG.
Sans cette sonde, un drapeau ignoré par Chromium ferait auditer deux fois le thème clair, et le job resterait vert.
Lire un rapport axe en cas d'échec¶
Le log du job affiche les violations au fil de l'audit, sous un bandeau === axe — thème <thème> === qui indique la passe concernée. Le détail se trouve dans les artifacts du job (bouton Browse ou Download) : var/axe-docs/docs-a11y-clair.json et var/axe-docs/docs-a11y-sombre.json. Ils sont conservés même quand le job échoue (when: always).
Chaque fichier contient un résultat par URL auditée. Dans chacun, le tableau violations liste les règles en échec :
| Champ | Contenu |
|---|---|
url |
Page auditée. |
violations[].id |
Identifiant de la règle axe (ex. color-contrast, scrollable-region-focusable). |
violations[].impact |
Gravité : minor, moderate, serious, critical. |
violations[].helpUrl |
Fiche de la règle sur le site de Deque. |
violations[].nodes[].target |
Sélecteur CSS de chaque élément fautif. |
violations[].nodes[].failureSummary |
Ce qu'il faut corriger sur cet élément. |
Si le log s'arrête avant le bandeau axe, l'échec vient de la garde sur l'artefact, du serveur (consulter var/log/docs-a11y-server.log) ou de la sonde de thème.
Corriger dans mkdocs/overrides, jamais par --disable ou --exclude¶
Le job ne passe aucune option --disable ni --exclude à axe. Une violation, y compris lorsqu'elle vient du gabarit Material, se corrige dans les surcharges de la doc : mkdocs/overrides/ (gabarits et stylesheets/kirexo-docs.css). Les corrections relevées par le premier audit en sont l'exemple, dans la section « 11-bis » de mkdocs/overrides/stylesheets/kirexo-docs.css :
| Règle axe | Correction |
|---|---|
color-contrast |
.md-copyright passe de --ink-3 à --ink-2 : --ink-3 sur le fond du pied de page (--surface-3) donnait 4,48:1, sous le seuil AA de 4,5:1. |
scrollable-region-focusable |
Les blocs de code (.md-typeset pre > code) passent à white-space: pre-wrap et overflow-wrap: anywhere : ils reviennent à la ligne au lieu de défiler horizontalement, ce qu'un utilisateur au clavier ne pouvait pas faire. |
Une exclusion ne serait envisageable que pour une violation impossible à surcharger côté Kirexo. Elle exigerait un commentaire de justification au-dessus de la commande et l'accord du mainteneur, car elle déroge à l'objectif RGAA AA de la doc.
Rejouer le job en local¶
Depuis un terminal hôte (le socket Docker est requis, et il est refusé dans le conteneur php) :
L'audit a besoin de l'artefact public/ de quality:docs-build : ce job amont doit être rejoué avant lui, sinon la garde sur l'artefact fait échouer le job dès sa première étape. Les rapports sont écrits dans var/axe-docs/. Détail de la cible : castor ci:local.
Job quality:site-check¶
Construit le site vitrine puis le vérifie (HTML valide, liens internes, quatre étapes d'installation identiques entre site/installer.html, le tutoriel mkdocs et install/README.md, axe WCAG 2.1 AA en clair et en sombre), avec exposition d'une preview dans la MR. Détail des contrôles : castor site:build et castor site:check.
Le job tourne sur toute MR, sans filtre changes: (.rules:no-tag). Il couvre donc aussi les MR limitées à docs/**, chemin doc-only pour lequel test:unit ne tourne pas (cf. Allowlists changes: des suites de tests) : une MR qui modifie une commande du tutoriel d'installation sans aligner la page du site et le README échoue ici. Détail du contrôle : Quatre étapes d'installation.
| Caractéristique | Valeur |
|---|---|
| Fichier | .gitlab/ci/quality.yml |
| Stage | quality |
| Image | $KIREXO_DEV_IMAGE (Chromium, chromedriver et Node déjà présents). |
needs: |
[] — détaché du DAG. Pas de composer install : Castor charge App\Castor\… par son autoloader de repli quand vendor/ est absent, et les classes de castor/src/Site/ n'utilisent que PHP natif. |
| Variables | npm_config_cache: "$CI_PROJECT_DIR/.npm" (cache npm de npx) ; CHROMEDRIVER_SKIP_DOWNLOAD: "true" (chromedriver de l'image, pas celui du paquet npm). |
| Cache | Clé site-npm préfixée, calculée sur package.json ; chemin .npm/. |
| Commande | castor site:build puis castor site:check. |
| Artifact | var/site-build/, expire_in: 1 week, exposé via expose_as: "Site vitrine preview". |
| Déclencheurs | .rules:no-tag — MR, main (hors CREATE_TAG=true). Ne tourne pas sur tag. |
interruptible |
true. |
SITE_DEPLOY_PROVIDER étant une variable non protégée, la preview cite dans ses mentions légales l'hébergeur qui recevra le déploiement. Dans la preview, les pages renvoient à leurs assets en relatif et s'affichent stylées ; seule 404.html, qui utilise des chemins absolus, s'affiche sans style quand on l'ouvre directement.
Job quality:shellcheck¶
Lint statique des scripts shell du dépôt.
| Caractéristique | Valeur |
|---|---|
| Stage | quality |
| Image | koalaman/shellcheck-alpine:stable — et non koalaman/shellcheck:stable, qui est scratch-based (binaire seul, sans sh ni find) et donc inutilisable dans un job GitLab. |
| Périmètre | find infra .claude/hooks .claude/skills -name '*.sh', puis xargs shellcheck --severity=warning --shell=bash. |
| Déclencheurs | .rules:no-tag — MR, main (hors CREATE_TAG=true). Ne tourne pas sur tag. |
Un find qui ne trouve rien fait passer le job au vert
Le script sort en 0 avec Aucun script shell à linter. quand la liste est vide. Un dossier renommé sans mise à jour du périmètre donnerait donc un job vert qui ne linte rien. Contrôle : find infra .claude/hooks .claude/skills -name '*.sh' | wc -l doit rendre un nombre strictement positif.
Parité avec castor lint:shell
Le job fait un find récursif ; la cible Castor, elle, énumère cinq glob non récursifs (cf. castor lint:shell). Les deux doivent couvrir le même ensemble de fichiers : un script placé à une profondeur non couverte par les globs passerait en local et échouerait en CI.
Job test:bash¶
Exécute bats --recursive tests/Bash/ dans $KIREXO_DEV_IMAGE (le paquet Alpine bats est installé au stage frankenphp_dev). needs: ["quality:shellcheck"] — inutile de tester des fonctions bash qui ne passent même pas le lint.
Les .bats sourcent leurs libs en chemin relatif, jamais par /app/...
En CI, le dépôt est checkouté dans /builds/… tandis que /app est une copie figée de l'image, sans les fichiers neufs de la branche. Un source /app/infra/… serait vert en local et rouge en CI. Les tests résolvent donc leurs cibles via $BATS_TEST_DIRNAME, et le job n'a aucun before_script : il n'existe plus de symlink /app/... à poser.
Job quality:confinement¶
Rejoue le contrat de confinement (.claude/skills/_shared/confinement.md) sur le sous-ensemble d'invariants vérifiables dans un job GitLab. Détail de la commande, des profils et des codes de sortie : castor confinement:check.
| Caractéristique | Valeur |
|---|---|
| Stage | quality |
| Image | $KIREXO_DEV_IMAGE (le binaire castor y est installé). |
needs: |
[] — détaché du DAG, démarre dès le début de pipeline. Le contrôle ne lit que des fichiers versionnés : il n'a besoin ni de vendor/, ni d'une base, ni de l'artifact d'un job amont. |
| Commande | castor confinement:check --profile=ci |
| Déclencheurs | .rules:no-tag — MR, main (hors CREATE_TAG=true). Ne tourne pas sur tag. |
interruptible |
true — un nouveau push sur la même MR annule le job en cours. |
| Effet en cas d'échec | Le job échoue (exit 1) → la MR ne peut pas être mergée tant qu'un invariant bloquant est violé. Seuls C1, C7 et C9 peuvent le faire échouer : le socket Docker du runner ne rougit pas le job (cf. Le socket Docker du runner). |
Ce que le profil ci exécute réellement :
| Invariant | Rendu en CI | Détail |
|---|---|---|
C1 — aucun montage hôte inattendu |
✓ OK / ✗ KO, bloquant |
Lit /proc/self/mountinfo et le confronte à la liste justifiée. |
C7 — process non-root |
✓ OK / ✗ KO, bloquant |
id -u ≠ 0. |
C9 — CI et prod non impactées |
✓ OK / ✗ KO, bloquant |
compose.yaml / compose.prod.yaml sans référence worktree ni proxy. |
C2 — aucun socket Docker joignable |
⚠ WARN, non bloquant |
Sonde exécutée, constat affiché avec sa raison (cf. ci-dessous). |
C2h — volet hôte de C2 |
· SKIP |
Sonde hôte-only : elle exigerait le socket Docker que C2 interdit dans le conteneur. Elle n'existe que sous le profil host, hors de portée d'un job CI. |
C3, C4, C5, C6, C8, C10 |
· SKIP |
Hors profil, avec leur raison affichée : réseau ouvert par conception dans un job CI, aucun montage hôte de whitelist ni d'espace Claude, aucun sudoers dans l'image, pas de worktree pair, aucun réseau partagé. |
Le job existe d'abord pour C9 : c'est le garde-fou qui empêche une modification liée aux worktrees d'atterrir dans le compose partagé avec la production. Le raisonnement complet est dans Modèle de menace et contrat de confinement.
Le socket Docker du runner¶
L'exécuteur docker du runner GitLab monte /var/run/docker.sock dans le conteneur de build — c'est le mécanisme par lequel les jobs docker:build-* atteignent le démon pour construire et pousser les images. Ce socket est un fait de l'infrastructure du runner : il n'est pas déclaré par le dépôt, aucun changement de code ne le fait disparaître, et le conteneur de l'agent — celui que C2 décrit — n'existe pas dans un job CI. Son exposition ici ne dit donc rien du confinement de l'agent.
En profil ci, C2 est en conséquence rendu ⚠ WARN plutôt que ✗ KO : la ligne reste exécutée et visible dans le rapport du job, avec son détail (socket Docker présent : /var/run/docker.sock — monté par l'exécuteur du runner GitLab, hors du périmètre de l'agent), mais ne compte pas dans le verdict. Elle n'est pas masquée en · SKIP — un SKIP muet est le mode de panne que ce contrat existe pour éliminer — et la sévérité de C2 au contrat reste blocking : dans le conteneur de dev, un socket joignable est un KO dur qui arme le gate SessionStart.
C'est le seul écart entre le contrat et son rendu en CI : C1, C7 et C9 se comportent en job exactement comme dans le conteneur de dev, sonde identique et verdict identique.
Cache Composer (build:vendor)¶
build:vendor (.gitlab/ci/quality.yml, stage quality) amorce le cache Composer en tête de pipeline. C'est le seul job en policy: pull-push : il réalise le composer install lourd au cache miss (téléchargement des dépendances) et télécharge le binaire CLI Tailwind via bin/console tailwind:build, puis pousse vendor/ et var/tailwind/ en cache. Tous les autres jobs PHP héritent du template .php_quality_job qui est passé en policy: pull (lecture seule) : ils récupèrent ce cache via la chaîne de needs (build:vendor → quality:cs-fix → reste) au lieu de télécharger vendor/ ou le binaire Tailwind chacun de leur côté.
| Caractéristique | Valeur |
|---|---|
| Stage | quality |
| Image | KIREXO_BASE_IMAGE (via .php_quality_job). |
needs: |
[] — détaché du DAG, démarre dès le début de pipeline. |
cache.policy |
pull-push (override du pull hérité de .php_quality_job). |
| Clé de cache | composer.lock (le cache est invalidé dès que le lock change). |
cache.paths |
vendor/ et var/tailwind/ — partagent la même clé composer.lock (le binaire Tailwind est versionné par symfonycasts/tailwind-bundle, présent dans le lockfile). |
script |
composer validate --strict --no-check-publish, bin/console tailwind:build, purge de vendor/**/.git (cf. ci-dessous) puis chown -R 1000:1000 vendor/ var/tailwind/ — le travail utile (composer install) est dans le before_script du template ; le push du cache se fait à la fin du job. |
Le composer validate --strict --no-check-publish détecte une MR qui modifie composer.json sans régénérer le composer.lock (un classique). --strict transforme les warnings (dépendances abandonnées, lock désynchro) en erreurs ; --no-check-publish ignore les champs « publication » (name/description/license) sans intérêt vu que le projet n'est pas un package Composer publié. La cible locale qui joue la même commande, avec les mêmes options, est castor composer:validate — première étape de castor all.
Le cache var/tailwind/¶
bin/console tailwind:build télécharge le binaire CLI tailwindcss (~30 Mo, Go statique) dans var/tailwind/ s'il est absent, puis compile le CSS. La version concrète est pilotée par symfonycasts/tailwind-bundle, lui-même épinglé dans composer.lock — d'où la clé de cache partagée avec vendor/ : tant que le lockfile ne bouge pas, le binaire en cache reste valide.
Il n'existe pas de commande tailwind:install
symfonycasts/tailwind-bundle n'expose que tailwind:init, tailwind:build, tailwind:config et tailwind:update (cf. vendor/symfonycasts/tailwind-bundle/src/Command/). Le téléchargement du binaire est un effet de bord de tailwind:build (TailwindBinary::getBinaryPath() → downloadExecutable()), pas d'une commande d'installation dédiée. build:vendor appelle donc tailwind:build — exactement la même commande que les jobs aval, ce qui garantit que le binaire mis en cache est celui qu'ils consommeront.
Sans cet amorçage, chaque job aval qui dépend de Tailwind re-téléchargerait ces ~30 Mo. Les consommateurs concrets dans la pipeline sont :
| Job | before_script consommateur |
Pourquoi |
|---|---|---|
test:unit |
bin/console tailwind:build (via .php_test_job) |
Les tests d'intégration WebTestCase qui font GET / chargent base.html.twig via l'importmap → un asset tailwindcss manquant déclencherait un 500. |
test:e2e |
bin/console tailwind:build (via .php_e2e_job) |
Panther charge la page comme un vrai navigateur → public/tailwind.css doit exister, sinon 500 « Built Tailwind CSS file does not exist ». |
Quand le binaire est déjà là (cache tiré), tailwind:build se contente de compiler le CSS : téléchargement une fois pour toute la chaîne, compilation à chaque job.
Objectif principal du job : éviter qu'une demi-douzaine de jobs PHP téléchargent vendor/ en parallèle au cache miss et écrasent concurremment le même cache.
Purge de vendor/**/.git avant le push du cache¶
Avant le chown et le push, le script compte puis supprime les dépôts git embarqués dans vendor/ :
_git_dirs=$(find vendor/ -mindepth 2 -maxdepth 3 -type d -name .git 2>/dev/null | wc -l)
if [ "$_git_dirs" -gt 0 ]; then
echo "→ purge de $_git_dirs dépôt(s) git embarqué(s) (repli --prefer-source détecté)"
find vendor/ -mindepth 2 -maxdepth 3 -type d -name .git -prune -exec rm -rf {} + || \
echo "⚠ purge incomplète — le cache poussé sera plus lourd que nécessaire." >&2
fi
Ces dossiers .git n'existent que si le before_script est retombé sur --prefer-source, qui clone chaque paquet depuis git au lieu d'en extraire l'archive. build:vendor étant le seul producteur de cache, un vendor/ alourdi de plusieurs centaines de mégaoctets serait ensuite tiré par tous les jobs de toutes les pipelines suivantes : la panne réseau d'un jour se paierait des semaines. vendor/**/.git n'a aucune utilité à l'exécution.
Le compte est affiché avant la suppression, et une purge partielle émet un avertissement sur stderr sans faire échouer le job : le dommage qu'un .git oublié causerait est un cache plus lourd, pas une pipeline fausse.
Le mode dégradé n'est pas sûr¶
En dégradé (cache absent), le composer install du before_script recrée vendor/ dans chaque job et tailwind:build retéléchargera son binaire. Ce mode est plus lent, et il peut casser — ce n'est pas un repli garanti.
Mesuré : quatre pipelines consécutives sont mortes ainsi. Un cache qui ne s'extrait pas, un composer.lock inchangé (donc build:vendor n'est même pas créé, cf. ses rules:changes ci-dessus), et chaque job se retrouve à retélécharger l'intégralité des archives dist. test:unit et test:e2e ont terminé en exit code 100 — un code Composer, avant le moindre test — sur un HTTP/2 400 de codeload.github.com, avec le message Source fallback is disabled. Not trying alternative sources.
Deux correctifs ont été posés depuis, dans le before_script de .php_quality_job :
- l'authentification Composer auprès de GitHub retire une cause probable d'échec (le quota anonyme par IP du runner), sans rendre
composer installinfaillible ; - le repli sur la source git donne un plan B quand l'archive
distest indisponible, ce que"preferred-install": {"*": "dist"}(composer.json) interdisait jusque-là.
Le mode dégradé reste plus lent, mais il n'est plus sans issue : c'est le repli --prefer-source, et non le cache, qui couvre désormais ce mode de panne.
Le cache n'est pas une accélération mesurée
Sur l'échantillon relevé (6 pipelines), les jobs qui extraient le cache ne sont pas plus rapides que ceux qui le manquent — test:unit tourne à 299 s de moyenne au cache hit contre 248 s au cache miss. La cause tient à l'architecture des runners, pas au dépôt : le cache GitLab est local au runner, pas distribué. Détail, chiffres et conséquences : Le coût réel d'une pipeline CI.
Tests et gate de couverture¶
Trois jobs du stage test portent la suite de tests : test:unit (suites unit + integration), test:e2e (suite Panther) et test:bash (fonctions bash via bats). La mesure de couverture est portée uniquement par test:unit : c'est lui qui calcule le pourcentage, porte la métrique coverage: (badge GitLab) et fait échouer le job si le gate n'est pas tenu.
Un seul gate de couverture est appliqué en CI : les lignes, à 100,00 % (règle CLAUDE.md).
La couverture de branches n'est pas mesurée par la pipeline. Elle se vérifie en local, fichier par fichier, avec castor test:path-coverage, au seuil ≥ 80 % — source de vérité du sujet : .claude/skills/_shared/tests-couverture-quota.md.
La raison de cette exclusion est une contrainte de ressources, pas un renoncement : pathCoverage instrumente lignes, branches et chemins sur tout src/, et sature la mémoire dès qu'un test charge le kernel Symfony UX (Live Component) — avec un memory_limit illimité, le job mourait sur un Bus error. L'attribut a donc été retiré du run global (phpunit.dist.xml), et le job tourne à php -d memory_limit=2G, suffisant pour la couverture de lignes seule.
Pourquoi la couverture sur test:unit seul¶
Choix assumé : la couverture est jugée sur les seules suites unit + integration. C'est suffisant tant que tout le code de prod y est couvert — ce qui est la règle par défaut du projet.
CLAUDE.md autorise un cas particulier : un controller invokable trivial peut être couvert uniquement par son test E2E. Comme test:e2e ne produit plus aucune couverture, un tel controller apparaîtrait alors comme non couvert côté test:unit et ferait tomber le job sous 100 %. La parade est de le couvrir aussi en integration (un test WebTestCase), de sorte qu'il compte dans la mesure de test:unit.
Job test:unit¶
| Caractéristique | Valeur |
|---|---|
| Stage | test |
| Template | .php_test_job (override de l'image). |
| Image | KIREXO_DEV_IMAGE (Xdebug requis pour la couverture — kirexo-base ne l'a pas). |
needs: |
quality:cs-fix |
| Suites PHPUnit | unit,integration |
XDEBUG_MODE |
coverage |
| Rapport JUnit | junit-unit.xml (tests dans la MR). |
| Cobertura | cobertura-unit.xml (--coverage-cobertura) — affichage des lignes couvertes dans le diff de la MR. |
coverage: regex |
/Lines:\s+(\d+(?:\.\d+)?%)/ — capte le Lines: NN.NN% réémis en fin de script. Seul job de la pipeline qui porte cette clé. |
| Plafond mémoire | php -d memory_limit=2G — override ciblé du 512M de frankenphp/conf.d/10-app.ini. Jamais -1. |
| Effet sous le seuil | Le gate inline termine en exit 1 → le job échoue → la MR ne peut pas être mergée. |
Gate de lignes (100,00 %)¶
Le gate est inline en shell, sans script externe. Le job lance phpunit --coverage-cobertura cobertura-unit.xml --coverage-text=coverage.txt, puis extrait la première ligne Lines: du résumé texte (le total global ; les détails par fichier viennent après), échoue si elle n'est pas à 100.00, et réémet ce total en dernière ligne Lines: du log pour que le regex coverage: du job capture bien le pourcentage global.
L'extraction est un sed -nE '/Lines:/{…;q}', et le q n'est pas une élégance : avec un sed … | head -1, sous set -eo pipefail, head fermait le pipe tôt et sed — qui continue d'écrire les quelque 190 lignes Lines: du rapport détaillé — recevait SIGPIPE, sortait en 141, et faisait échouer le job à couverture 100 %. Le q supprime le pipe, donc la course.
memory_limit=-1 est une régression connue, pas une simplification
Couplé à l'ancien pathCoverage="true", un plafond illimité produisait un Bus error (core dump) dès qu'un test chargeait le kernel Symfony UX. Le plafond borné à 2G et le retrait de pathCoverage du run global sont les deux moitiés du même correctif : rétablir l'un sans l'autre ramène le crash.
Dépendance vis-à-vis de PHP-CS-Fixer
L'atteignabilité du gate ≥ 90 % dépend de la règle native_function_invocation configurée dans .php-cs-fixer.dist.php. Sans elle, chaque appel à une fonction interne dans un namespace émet un opcode JMP_FRAMELESS dont le slow path compte comme branche non couverte côté Cobertura. La règle est donc une dépendance directe du gate au même titre que pathCoverage="true". Mécanique détaillée et conséquences pour les contributeurs : Exécuter les tests — Ne pas désactiver native_function_invocation.
Job test:e2e¶
test:e2e exécute la suite Panther (parcours navigateur, Chromium headless) et publie son JUnit. Il ne produit aucune couverture : pas de XDEBUG_MODE, pas d'option --coverage-* — ce qui allège le run E2E.
| Caractéristique | Valeur |
|---|---|
| Stage | test |
| Template | .php_e2e_job |
| Image | KIREXO_DEV_IMAGE (Chromium + chromedriver). |
needs: |
quality:cs-fix |
| Suite PHPUnit | e2e |
| Rapport JUnit | junit-e2e.xml (tests dans la MR). |
| Couverture | Aucune — la mesure est portée par test:unit. |
artifacts.paths |
var/error-screenshots/, var/log/test.log, var/log/chrome.log — exposés when: always, expirent au bout d'1 semaine. |
test:e2e conserve un seul garde-fou spécifique à Panther/Chromium : un timeout réduit pour ne pas immobiliser un runner sur un navigateur bloqué.
| Caractéristique | Valeur |
|---|---|
timeout |
20m — borne le job sous le timeout projet pour ne pas immobiliser un runner sur un navigateur bloqué. |
Pas de retry: configuré. Raison : workflow.auto_cancel.on_job_failure: all annule tous les jobs en cours de la pipeline dès qu'un job échoue, avant qu'un retry n'ait eu le temps de repartir. Un E2E qui flake une fois coupait donc l'intégralité de la pipeline pour rien — le retry ne servait à rien. La flakiness est désormais traitée à la source (timing, fixtures, sélecteurs) plutôt que masquée par un rejeu.
Artifacts de debug¶
var/error-screenshots/ n'est créé par Panther que sur échec d'au moins un test — la directive PANTHER_ERROR_SCREENSHOT_DIR du phpunit.dist.xml pointe sur ce dossier, et Panther dump un PNG du DOM à l'instant du KO pour chaque assertion en erreur. Une capture vaut mieux qu'une stack trace XML : elle montre littéralement l'état réel de la page au moment de l'échec (champ vide, erreur 500 stylée Symfony, redirection inattendue, modal qui n'a pas eu le temps de s'ouvrir). Sur une MR rouge, les captures sont consultables depuis l'onglet Artifacts → Browse du job sans git pull ni rerun verbeux.
var/log/test.log capture la sortie applicative en parallèle. Sur succès, ces deux paths restent essentiellement vides — GitLab n'accepte qu'un seul bloc artifacts: par job avec une seule directive when:, le compromis when: always garde le contrat « JUnit toujours publié » sans gymnastique sur les paths.
var/log/chrome.log est le log verbeux du navigateur Chromium, activé par les flags --enable-logging --v=1 --log-file de PANTHER_CHROME_ARGUMENTS (.env.test, cf. Variables d'environnement). Contrairement aux deux précédents, il est présent même quand Chrome ne démarre pas : c'est lui qui contient la cause exacte d'un « session not created: Chrome instance exited » (flag manquant, bibliothèque système absente, sandbox, GPU, version incompatible).
Voir aussi
Procédure de lecture de ces artefacts pour isoler un échec : Diagnostiquer un échec E2E en CI.
Images publiées dans le registry¶
Cinq images sont publiées dans le registry du projet ($CI_REGISTRY_IMAGE). Trois sont construites à partir des stages du Dockerfile racine ; les deux autres (kirexo-docs, kirexo-supply-chain) à partir de Dockerfiles dédiés. Le nom complet d'une image est de la forme registry.gitlab.com/<group>/<project>/<image>:<tag>.
| Image | Dockerfile / stage | Tag mobile | Contenu | Usage CI |
|---|---|---|---|---|
kirexo-base |
racine, frankenphp_base |
:php8.5-alpine |
Extensions PHP, sans Chromium ni Node. Tourne en root. | Jobs PHP « légers » sans driver de couverture (build:vendor, quality:cs-fix, quality:composer-audit, quality:phpstan, quality:lint). |
kirexo-dev |
racine, frankenphp_dev |
:php8.5-alpine |
Hérite de base + Chromium, chromedriver, Node, Xdebug, outils dev. | test:bash (bats inclus), test:e2e (Panther + Chromium headless), test:unit (Xdebug requis pour la couverture), quality:confinement (binaire castor inclus). |
kirexo-prod |
racine, frankenphp_prod |
:php8.5-alpine |
Image de production. | Déploiement — n'est jamais utilisée comme image de runner. C'est elle que compose.prod.yaml pull (cf. Image de production). |
kirexo-docs |
mkdocs/Dockerfile |
:latest |
mkdocs-material + plugins (imaging via Pillow/CairoSVG, git-revision-date). | Job pages (build mkdocs strict, cf. Job pages). |
kirexo-supply-chain |
supply-chain/Dockerfile |
:latest |
Alpine 3.22 + binaires officiels cosign et syft, copiés depuis les images upstream (gcr.io/projectsigstore/cosign et anchore/syft) via un multi-stage Docker COPY --from=. |
Jobs docker:sign-prod (signature keyless) et release:sbom (génération SPDX + CycloneDX) — cf. Image supply chain. |
Sur création de tag, les tags poussés diffèrent selon l'image :
| Image | Tags poussés sur création de tag |
|---|---|
kirexo-base |
:php8.5-alpine + :latest |
kirexo-dev |
:php8.5-alpine + :latest |
kirexo-prod |
:php8.5-alpine + :latest + :$CI_COMMIT_TAG (le tag Git de version, ex. kirexo-prod:0.0.1), trois références vers le même index : linux/amd64 + linux/arm64, ou linux/amd64 seul si la jambe arm64 n'a pas abouti. En plus, les tags intermédiaires :$CI_COMMIT_TAG-amd64 et, si la jambe arm64 a poussé, :$CI_COMMIT_TAG-arm64 (cf. Construction multi-architecture de kirexo-prod). |
kirexo-docs |
:latest (tag unique) |
kirexo-supply-chain |
:latest (tag unique) |
Architectures publiées :
| Image | Architectures |
|---|---|
kirexo-prod, références :$CI_COMMIT_TAG, :latest et :php8.5-alpine poussées sur tag |
linux/amd64 + linux/arm64, ou linux/amd64 seule si la jambe arm64 a échoué ou n'a pas démarré (index OCI dans les deux cas ; la note de release le signale par une section « Architecture ») |
kirexo-prod:php8.5-alpine poussée en MR |
linux/amd64 seule |
kirexo-base, kirexo-dev, kirexo-docs, kirexo-supply-chain |
linux/amd64 seule |
Statut des tags kirexo-prod :
| Tag | Statut |
|---|---|
:$CI_COMMIT_TAG |
Installable. Tag de version immuable, celui qu'épingle KIREXO_VERSION. |
:latest |
Installable, mobile : réécrit à chaque release. |
:php8.5-alpine |
Mobile, réécrit en amd64 seul par toute MR qui pousse l'image prod : ni stable, ni multi-architecture. Aucun consommateur hors CI. |
:$CI_COMMIT_TAG-amd64, :$CI_COMMIT_TAG-arm64 |
Intermédiaires, non installables. Poussés par chaque jambe de build, sources de l'index. Hors contrat d'installation : ni install/, ni compose.prod.yaml ne les citent. Un tag d'architecture présent dans l'index est signé et vérifiable (il pointe une image enfant de l'index signé). Un :$CI_COMMIT_TAG-arm64 absent de l'index est orphelin : ni signé, ni vérifiable ; il signale une jambe arm64 tombée après son push (smoke-tests post-push), et l'index a été assemblé sans lui. La seule présence de :$CI_COMMIT_TAG-amd64, sans :$CI_COMMIT_TAG, signale une pipeline de tag interrompue avant l'index. Purgés par la cleanup policy avec le tag de version (cf. Configurer la cleanup policy du registry). |
Le double tag :php8.5-alpine ET :latest permet aux pipelines suivantes de toujours pointer vers :php8.5-alpine (version PHP pinnée) tout en gardant un :latest lisible côté UI.
kirexo-prod reçoit en plus un troisième tag immuable :$CI_COMMIT_TAG (le tag Git de version sémantique, kirexo-prod:<x.y.z>). Le :latest poussé sur tag ne peut jamais reculer : les tags ne sont créés que depuis main et le job tag:create impose une version strictement supérieure à la dernière. C'est ce tag de version que la production épingle via KIREXO_VERSION dans compose.prod.yaml pour un pin de version et un rollback déterministe (cf. Déployer Kirexo en production). kirexo-base et kirexo-dev n'en ont pas besoin : côté CI elles sont toujours référencées par :php8.5-alpine. Les images kirexo-docs et kirexo-supply-chain ne portent qu'un tag :latest unique : elles ne dépendent pas de PHP et leur contenu (un environnement d'outillage CI) n'a pas de version à épingler — leur versionnement se fait via le tag des FROM de leur Dockerfile respectif, suivi automatiquement par le manager dockerfile de Renovate.
Le tag de version PHP n'est pas codé en dur — il est dérivé de la variable racine PHP_VERSION (.gitlab-ci.yml). Une montée de version PHP se résume à modifier cette ligne puis à rebuilder les trois images du Dockerfile racine.
Jobs de build¶
Les jobs de build partagent un template .docker_job qui charge docker:29 + docker:29-dind, s'authentifie sur le registry via CI_REGISTRY_USER/CI_REGISTRY_PASSWORD et active BUILDKIT_INLINE_CACHE=1 pour que --cache-from reste efficace d'un job au suivant (DinD repart à vide à chaque job).
| Job | Cible / Dockerfile | Tag produit | Déclencheur |
|---|---|---|---|
docker:build-base |
racine, frankenphp_base |
$CI_REGISTRY_IMAGE/kirexo-base:php8.5-alpine |
Manuel (▶) sur main hors schedule et en MR (.rules:docker). Absent du schedule. Automatique sur tag. needs: []. |
docker:build-dev |
racine, frankenphp_dev |
$CI_REGISTRY_IMAGE/kirexo-dev:php8.5-alpine |
Automatique sur main, pipelines push et web uniquement, quand l'un des fichiers de ses changes est modifié : Dockerfile, .gitlab/ci/docker.yml et chaque source de COPY (hors --from=) des stages frankenphp_base et frankenphp_dev. Absent en MR et en schedule. Automatique sur tag. Règles propres (ne référence pas .rules:docker), aucun needs. |
docker:build-prod |
racine, frankenphp_prod |
En MR : $CI_REGISTRY_IMAGE/kirexo-prod:php8.5-alpine (amd64). Sur tag : $CI_REGISTRY_IMAGE/kirexo-prod:$CI_COMMIT_TAG-amd64 seul — jambe amd64 de l'index. |
Automatique en MR si .dockerignore, Dockerfile, .gitlab/ci/docker.yml, infra/image/check-prod-image*.sh, infra/image/smoke-prod-image*.sh, infra/image/compose.smoke.yaml, config/**/* ou compose*.yaml change ; manuel sinon en MR. Jamais sur main (when: never, schedule compris). Automatique sur tag. Aucun needs : n'attend jamais docker:build-base. Cf. Garde-fou de l'image prod avant push et Smoke test HTTP de l'image prod avant push. |
docker:build-prod-arm64 |
racine, frankenphp_prod |
$CI_REGISTRY_IMAGE/kirexo-prod:$CI_COMMIT_TAG-arm64 |
Tag de release uniquement. Runner saas-linux-small-arm64. Aucun needs. allow_failure: true (best-effort). Artifact reports: dotenv: prod-arm64.env (KIREXO_PROD_ARM64_BUILT=true), publié seulement si la jambe a tout réussi. Cf. Construction multi-architecture de kirexo-prod. |
docker:manifest-prod |
— (aucun build) | $CI_REGISTRY_IMAGE/kirexo-prod:$CI_COMMIT_TAG, :latest, :php8.5-alpine (index linux/amd64 seul, ou linux/amd64 + linux/arm64) |
Tag de release uniquement. needs : docker:build-prod et docker:build-prod-arm64 avec artifacts: true. |
docker:build-docs |
mkdocs/Dockerfile |
$CI_REGISTRY_IMAGE/kirexo-docs:latest |
Automatique sur main quand mkdocs/Dockerfile change, manuel sur main sinon. Manuel sur MR. Automatique sur tag. needs: [] — indépendant de docker:build-base. |
docker:build-supply-chain |
supply-chain/Dockerfile |
$CI_REGISTRY_IMAGE/kirexo-supply-chain:latest |
Automatique sur main quand supply-chain/Dockerfile change, manuel sur main sinon. Manuel sur MR. Automatique sur tag. needs: [] — indépendant de docker:build-base. |
Le hidden job .rules:docker (.gitlab-ci.yml) est référencé par docker:build-base, pour toutes ses règles, et par docker:build-prod, en dernière position après sa règle MR et sa clause when: never sur main. docker:build-dev ne le référence pas. Ses règles, dans l'ordre :
| Contexte | Condition | Comportement |
|---|---|---|
main hors schedule |
$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CREATE_TAG != "true" && $CI_PIPELINE_SOURCE != "schedule" |
Manuel (bouton ▶, allow_failure: true). |
| Merge Request | $CI_PIPELINE_SOURCE == "merge_request_event" |
Manuel (bouton ▶, allow_failure: true). |
| Tag de release | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ |
Automatique (on_success). |
Une pipeline planifiée tourne sur main : sans l'exclusion du schedule, docker:build-base y apparaîtrait en manual et mettrait container_scanning:builders en skipped (cf. Jobs container_scanning:builders).
Chaînage docker:build-base → dev / prod¶
frankenphp_dev et frankenphp_prod dérivent tous deux de frankenphp_base (FROM frankenphp_base dans le Dockerfile). Les deux jobs pullent $KIREXO_BASE_IMAGE et le passent en --cache-from. Aucun des deux n'attend docker:build-base : ni l'un ni l'autre ne porte de needs, au niveau du job comme dans ses règles. Sans needs, un job suit l'ordre des stages et, avec when: on_success, ne part que si aucun job des stages précédents n'a échoué (hors allow_failure).
docker:build-dev porte ses propres règles, évaluées dans cet ordre :
| Contexte | Comportement de docker:build-dev |
|---|---|
| Tag semver | Automatique (on_success). Tourne en parallèle de docker:build-base, avec en --cache-from le base précédemment publié. Le build peut être plus lent si le stage base a changé ; l'image produite est identique. |
main, pipeline push ou web, avec changement de l'image dev |
Automatique (on_success). Part après les stages quality et test : une image dev n'est jamais publiée depuis un main rouge. |
main, pipeline push, sans changement de l'image dev |
Job non créé. |
main, pipeline api (glab ci run) |
Job non créé : la règle est bornée à push et web. |
| MR | Job non créé. Une MR qui modifie le stage dev est testée avec l'image dev publiée ; la nouvelle image est construite dès le merge sur main. |
| Schedule | Job non créé. |
Pipeline CREATE_TAG=true |
Job non créé (garde $CREATE_TAG != "true"). |
« Changement de l'image dev » désigne la liste changes de la règle main : Dockerfile, .gitlab/ci/docker.yml et chaque source de COPY (hors --from=) des stages frankenphp_base et frankenphp_dev. La garde R9 de tests/Unit/Infra/GitlabCiRulesGuardrailsTest.php parse le Dockerfile et échoue si une de ces sources manque à la liste : ajouter un COPY dans ces stages impose d'ajouter sa source dans .gitlab/ci/docker.yml.
Hors pipeline push, GitLab évalue changes à vrai. Deux conséquences :
- Run pipeline (source
web) surmainreconstruit toujours l'image dev. C'est le moyen de relancer une reconstruction ponctuelle, tant quekirexo-baseetkirexo-devexistent dans le registry et que les stagesqualityettestpassent. - Sans borne explicite, le schedule reconstruirait l'image chaque jour. La condition
$CI_PIPELINE_SOURCE =~ /^(push|web)$/l'exclut, et exclut aussi les pipelinesapi.
Si seul le stage base change, kirexo-base n'est pas republiée sur main : docker:build-base y reste manuel. docker:build-dev reconstruit les couches base en interne ; les jobs .php_quality_job tournent sur l'ancienne kirexo-base jusqu'au prochain tag ou à un ▶ sur docker:build-base.
docker:build-prod :
| Contexte | Comportement de docker:build-prod |
|---|---|
| Tag | Sans needs, le job suit l'ordre des stages : il attend la fin du stage quality, qui sur tag se réduit à quality:composer-audit (cf. Optimisation pipeline de tag). Il construit la jambe amd64 et ne pousse que kirexo-prod:$CI_COMMIT_TAG-amd64 (cf. Construction multi-architecture de kirexo-prod). Une CVE publiée entre le merge et le tag fait échouer l'audit : l'image prod n'est pas construite, et docker:manifest-prod, docker:sign-prod, release:sbom, release:bundle-render, docker:test-install, docker:test-install-traefik, release:bundle-publish et release:create ne tournent pas. C'est une barrière voulue : on ne publie pas une image vulnérable. Une fois l'audit vert, le job tourne quasiment en parallèle de docker:build-base, avec en --cache-from le base précédemment publié dans le registry. Le build peut être plus lent si le stage base a changé ; l'image produite est identique, frankenphp_prod étant reconstruit en entier depuis le Dockerfile. |
main (push, web, schedule) |
Job non créé : la clause if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH / when: never précède le !reference [.rules:docker, rules]. Le tag mobile kirexo-prod:php8.5-alpine qu'il poussait sur main n'avait aucun consommateur hors tag. |
| MR touchant un fichier déclencheur | Part automatiquement et exécute le garde-fou puis le smoke test HTTP (cf. Garde-fou de l'image prod avant push et Smoke test HTTP de l'image prod avant push). |
| MR sans fichier déclencheur | Manuel (▶), démarre sans attendre docker:build-base. |
En MR, le build reste mono-architecture (amd64) : ni docker:build-prod-arm64, ni docker:manifest-prod, ni docker:sign-prod n'existent dans la pipeline.
Pourquoi aucun needs sur docker:build-dev ni sur docker:build-prod :
- un besoin sur un job présent mais
manualnon joué (docker:build-baseen MR et surmain) n'est jamais satisfait et met le job enskipped.optional: truene couvre que l'absence du job dans la pipeline, pas ce cas. Le garde-fou dedocker:build-prodne tournait donc jamais en MR (constaté sur la MR !337).docker:build-devsortaitskippedsurmain, etkirexo-devn'était republiée qu'au tag (#270) ; - l'override
rules:needs: []posé sur la seule règle MR a été ignoré par GitLab.com : le besoin effectif restaitdocker:build-base(constaté sur la MR !339) ; - ce
needsn'était qu'une optimisation de cache : le base ne sert qu'en--cache-from.
Ce comportement de needs: optional face à un job manual est empirique : la documentation GitLab ne le décrit pas. Il est verrouillé par les gardes R8 et R9 de tests/Unit/Infra/GitlabCiRulesGuardrailsTest.php.
docker:build-docs et docker:build-supply-chain sont needs: [] : leurs images ne dérivent d'aucun stage du Dockerfile racine, ils ne dépendent donc pas de docker:build-base.
Garde-fou de l'image prod avant push de docker:build-prod¶
Entre le docker build --target frankenphp_prod (suivi du contrôle d'architecture) et le push, le job exécute :
Le script contrôle trois choses dans l'image de production :
- aucun outillage IA de développement n'y est embarqué. Ces fichiers sont écartés du contexte de build par
.dockerignore(cf. Contexte de build filtré par.dockerignore) ; le contrôle détecte le retrait accidentel d'une de ces lignes ; - les assets compilés sont présents. Ils sont produits par
asset-map:compiledans le stagefrankenphp_prod(cf. Construction des assets) ; sans eux, toute page répond 500 ; - les extensions PHP obligatoires sont chargées.
pcntl, installée dans le stagefrankenphp_prod(cf.pcntldans le stage prod), permet au worker Messenger d'honorer leSIGTERMdedocker stop; sans elle, l'arrêt se termine enSIGKILL.
| Élément contrôlé | Chemin ou nom dans l'image | Manquement si |
|---|---|---|
| Chemins interdits | /app/.agents, /app/.mcp.json, /app/AGENTS.md, /app/CLAUDE.md, /app/mate, /app/infra/mcp, /app/.claude, /app/site, /app/docs |
présent |
| Exécutable | claude résolu par command -v dans le PATH de l'image |
trouvé |
| Chemins obligatoires | /app/public/assets/manifest.json, /app/public/assets/importmap.json |
absent |
| Extensions PHP obligatoires | pcntl, testée par php -r 'exit(extension_loaded("pcntl") ? 0 : 1);' |
non chargée |
Un chemin interdit compte comme présent s'il existe, ou s'il s'agit d'un lien symbolique, même cassé. Un chemin obligatoire compte comme absent s'il n'existe pas (test [ -e ]).
Chaque liste vit dans une seule source, dans infra/image/check-prod-image.lib.sh :
| Fonction | Liste | Contrainte |
|---|---|---|
prod_image_forbidden_paths |
Chemins interdits | Alignée ligne à ligne sur .dockerignore. |
prod_image_required_paths |
Chemins obligatoires | Alignée sur les fichiers écrits par asset-map:compile. |
prod_image_required_extensions |
Extensions PHP obligatoires (pcntl) |
Un nom par ligne, tel qu'accepté par extension_loaded. Alignée sur les install-php-extensions du stage frankenphp_prod. |
Exécution de la sonde. Le script lance une sonde dans l'image locale :
| Option | Raison |
|---|---|
--pull never |
L'image inspectée est celle qui vient d'être construite, jamais une référence tirée du registry. |
--network none |
La sonde n'a besoin d'aucun réseau. |
--entrypoint /bin/sh |
Même raison que les smoke-tests post-push : le docker-entrypoint attendrait 60 s une base de données absente. |
Pas de --user |
L'image est contrôlée telle qu'elle tourne (user app, PATH de l'image). |
La sonde n'utilise que des builtins POSIX ([, command -v, printf), plus php -r pour le test des extensions, dont la sortie est rendue silencieuse. Elle émet, dans cet ordre :
| Ligne émise | Condition | Ligne de rapport correspondante |
|---|---|---|
PRESENT <chemin absolu> |
chemin interdit trouvé | ✗ chemin interdit présent : <chemin> |
MISSING <chemin absolu> |
chemin obligatoire absent | ✗ chemin obligatoire absent : <chemin> |
CLAUDE <chemin> |
exécutable claude trouvé |
✗ exécutable claude dans le PATH : <chemin> |
NOEXT <extension> |
extension obligatoire non chargée | ✗ extension PHP obligatoire absente : <extension> |
END |
toujours, en dernier | — (sentinelle) |
Chaque ligne PRESENT, MISSING, CLAUDE ou NOEXT compte pour un manquement. Toute autre ligne (bruit de l'image) est ignorée.
Codes de sortie.
| Code | Cas | Sortie |
|---|---|---|
0 |
Sentinelle reçue, aucun manquement. | ✓ Image conforme : aucun chemin interdit (9 chemins + exécutable claude contrôlés), 2 assets compilés présents, 1 extension(s) PHP requise(s) chargée(s). Les trois compteurs sont calculés depuis les fonctions de liste, pas écrits en dur. |
1 |
Sentinelle reçue, au moins un manquement. | Une ligne ✗ par manquement, tous listés, puis Image NON CONFORME — N manquement(s). Vérifier .dockerignore et le stage frankenphp_prod du Dockerfile. |
2 |
Usage invalide, docker introuvable, docker run en échec (image absente, pas de /bin/sh…) ou sentinelle END absente. |
Inspection impossible de <image> … ou ✗ Sonde incomplète … |
Le contrôle échoue fermé : une sortie vide ou tronquée ne vaut jamais « conforme ». Un code non nul fait échouer le job avant le docker push : l'image non conforme n'est pas poussée, et rien de ce qui suit n'est exécuté : ni le smoke test HTTP, ni les smoke-tests post-push, ni la pose des tags.
Déclenchement. Le job porte une règle placée avant !reference [.rules:docker, rules] : en pipeline de MR, il part automatiquement (when: on_success, donc allow_failure: false) dès que la MR modifie l'un des fichiers de la chaîne du garde-fou ou du smoke test HTTP :
Entrée de changes: |
Raison |
|---|---|
.dockerignore |
Filtre le contexte de build ; son retrait accidentel d'une ligne réintroduit l'outillage IA. |
Dockerfile |
Définit le stage frankenphp_prod contrôlé. |
.gitlab/ci/docker.yml |
Modifier la définition du job le rejoue. |
infra/image/check-prod-image.sh |
Script du garde-fou. |
infra/image/check-prod-image.lib.sh |
Listes de chemins et d'extensions sourcées par le garde-fou. |
infra/image/smoke-prod-image.sh |
Script du smoke test HTTP. |
infra/image/smoke-prod-image.lib.sh |
Fonctions sourcées par le smoke test HTTP. |
infra/image/compose.smoke.yaml |
Surcharge Compose qui définit la stack testée. |
config/**/* |
Une configuration chargée seulement en prod (when@prod) n'est jamais exercée par les E2E, qui tournent en APP_ENV=test : c'est la classe de défaut (handler Gelf fatal sans Graylog) qui rendait toutes les pages de l'image prod en 500 avec une CI verte (#260). |
compose*.yaml |
La stack éphémère du smoke test empile compose.yaml et compose.prod.yaml ; un service qui change doit la rejouer. Le motif couvre aussi compose.override.yaml (dev) : faux positif accepté. |
Un manquement du garde-fou ou un contrôle HTTP en échec rend alors la pipeline de MR rouge.
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
changes:
- .dockerignore
- Dockerfile
- .gitlab/ci/docker.yml
- infra/image/check-prod-image.sh
- infra/image/check-prod-image.lib.sh
- infra/image/smoke-prod-image.sh
- infra/image/smoke-prod-image.lib.sh
- infra/image/compose.smoke.yaml
- "config/**/*"
- "compose*.yaml"
when: on_success
Cette règle ne porte pas de needs, et le job non plus : c'est ce qui garantit que le garde-fou démarre en MR au lieu d'être skipped derrière docker:build-base resté manuel. Le détail et le compromis sur tag sont décrits dans Chaînage docker:build-base → dev / prod.
Dans les autres cas (MR sans changement de ces fichiers, tag), les règles de .rules:docker s'appliquent ; sur main, la clause when: never qui les précède l'emporte (cf. Chaînage docker:build-base → dev / prod).
Conséquences :
config/**/*change souvent :docker:build-prodpart automatiquement sur une part significative des MR, et chacune paie le build de l'image prod plus le smoke test HTTP ;- une MR qui déclenche le job pousse aussi le tag mobile
kirexo-prod:php8.5-alpinesi l'image passe les deux contrôles ; la prod épingle:$CI_COMMIT_TAGet ne tire jamais ce tag mobile.
POSIX sh. Les deux scripts portent le shebang #!/bin/sh et n'utilisent aucun bashisme : l'image docker:29 du job n'a pas bash. Ils sont toujours appelés par sh <chemin>.
Le même contrôle se rejoue depuis un poste de dev, côté hôte : castor docker:check-prod-image.
Smoke test HTTP de l'image prod avant push de docker:build-prod¶
Le garde-fou ci-dessus ne contrôle que des fichiers : il laisse passer une image dont toutes les pages répondent 500. Aucun autre job ne démarre l'image prod — les E2E tournent dans l'image de dev, en APP_ENV=test, où la configuration when@prod n'est jamais chargée. Le job exécute donc, juste après le garde-fou et avant le push :
- sh infra/image/check-prod-image.sh "$KIREXO_PROD_IMAGE"
- sh infra/image/smoke-prod-image.sh "$KIREXO_PROD_IMAGE"
- |
if [ -n "${CI_COMMIT_TAG:-}" ]; then
arch_ref="$CI_REGISTRY_IMAGE/kirexo-prod:$CI_COMMIT_TAG-$KIREXO_PROD_ARCH"
docker tag "$KIREXO_PROD_IMAGE" "$arch_ref"
docker push "$arch_ref"
else
docker push $KIREXO_PROD_IMAGE
fi
Le même script sert aux deux jambes de la pipeline de tag : le smoke test HTTP tourne donc aussi, nativement, sur arm64 (cf. Construction multi-architecture de kirexo-prod).
L'appel est une entrée de liste seule, jamais dans un bloc | : GitLab contrôle le code de sortie de chaque entrée de script:. Aucun || true ni allow_failure ne le neutralise.
Ce que fait infra/image/smoke-prod-image.sh. Dans le démon dind du job, le script :
- monte une stack prod éphémère —
compose.yaml+compose.prod.yaml+infra/image/compose.smoke.yaml— qui démarre l'image locale fraîchement construite, jamais tirée du registry, puis attend que le serveur HTTP réponde (GET /toutes les 2 s, 120 s maximum, réglable parKIREXO_SMOKE_HTTP_TIMEOUT) : le healthcheck compose, qui sonde l'admin Caddy:2019, passe au vert avant que FrankenPHP en mode worker n'ouvre les ports 80/443 ; - génère des secrets jetables pour l'exécution, et exporte les cinq variables d'exécution obligatoires de
compose.prod.yaml(KIREXO_RESERVED_DOMAINS=localhost,DEFAULT_URI=https://localhost,MAILER_DSN=null://null,MAILER_FROM_ADDRESS=noreply@example.org,MERCURE_PUBLIC_URL=https://localhost/.well-known/mercure) : sans cet export, l'interpolation les lirait dans le.envdu dépôt.MAILER_DSN=null://nullgarantit qu'aucun e-mail réel ne part ; - joue les migrations Doctrine et un seed SQL (admin, carnet, article publié) ;
- exécute les contrôles HTTP depuis le conteneur
php(docker compose exec -T php curl …) : l'imagedocker:29du job n'a ni bash ni curl, le script est en POSIX sh ; - en cas d'échec, affiche le diagnostic (
var/log, stderr des commandes,docker compose logs php) dans la trace ; - démonte toujours la stack (
trap), succès comme échec, sans supprimer l'image testée.
Le détail des douze contrôles (de stack-up à analyze-button-on), de la stack et du diagnostic est décrit dans castor docker:smoke-prod-image, qui encapsule le même script.
| Code | Cas |
|---|---|
0 |
Image servable : les douze contrôles sont verts. |
1 |
Image non servable : au moins un contrôle en échec ou non exécuté (statut HTTP inattendu, timeout, stack qui ne démarre pas). |
2 |
Usage invalide, docker ou plugin docker compose introuvable, image absente localement. |
Durée. À la sortie, le trap du script émet dans la trace la ligne :
sur succès comme sur échec. Le job n'ajoute aucun chronométrage de son côté. Ordre de grandeur attendu : 1 à 2 minutes, dont une part liée au tirage des images tierces de la stack (Postgres, Redis, RabbitMQ, Typesense…) depuis Docker Hub, dind repartant à vide à chaque job. La durée réelle se lit dans la trace de chaque exécution.
Effet en cas d'échec. Un code non nul fait échouer le job avant le docker push : l'image non servable n'est pas poussée dans le registry et les smoke-tests post-push ne tournent pas. En MR, le tag mobile kirexo-prod:php8.5-alpine reste sur l'image précédente. Sur tag, le tag d'architecture de la jambe n'est pas poussé. Jambe amd64 : docker:manifest-prod ne tourne pas et aucune référence publique (:$CI_COMMIT_TAG, :latest) n'est créée. Jambe arm64 (best-effort) : le signal KIREXO_PROD_ARM64_BUILT n'est pas écrit, et l'index est assemblé en linux/amd64 seul.
Rejouer côté hôte. Le même contrôle se lance depuis un poste de dev, en terminal hôte : castor docker:smoke-prod-image.
Ce contrôle versionné remplace entièrement la vérification manuelle de l'image prod menée lors du ticket #260 (critère 4 : clé API enregistrée, stockée chiffrée en base, puis bouton « Analyser la conformité » actif), couverte par les contrôles apikey-save, apikey-cipher et analyze-button-on.
Smoke-test post-push (plateforme et autoload) de docker:build-prod¶
À ne pas confondre avec le smoke test HTTP, qui démarre l'application avant le push : les contrôles de cette section ne démarrent pas l'application et ne vérifient que la plateforme PHP et l'autoload.
Après le push (kirexo-prod:php8.5-alpine en MR, kirexo-prod:$CI_COMMIT_TAG-<arch> sur tag), le job exécute deux smoke-tests sur l'image locale $KIREXO_PROD_IMAGE, celle qui vient d'être poussée. Coût ~3 s. Objectif : détecter avant l'assemblage de l'index public (et donc avant qu'un déploiement de prod ne puisse le pull) un autoload cassé, un fichier source manquant dans l'image, ou une extension PHP requise par une dépendance et absente du Dockerfile.
| # | Commande | Capture |
|---|---|---|
| 1 | docker run --rm --entrypoint composer $KIREXO_PROD_IMAGE check-platform-reqs --no-dev |
Version PHP de l'image et ensemble des extensions ext-* requises — directes ET transitives (la vérification lit composer.lock embarqué dans l'image). Capture le cas typique où une dépendance Symfony/Doctrine exige ext-intl ou ext-zip qui n'est pas listée dans composer.json directement et qui manque du Dockerfile. |
| 2 | docker run --rm --entrypoint php $KIREXO_PROD_IMAGE -r "require '/app/vendor/autoload.php'; class_exists('App\\Kernel') \|\| exit(1);" |
Autoload chargeable et classe App\Kernel résoluble depuis l'image. Capture un COPY trop restrictif dans le Dockerfile (src/ oublié), un .dockerignore qui exclut un dossier source, ou un autoload corrompu. |
Les deux commandes overrident --entrypoint parce que le docker-entrypoint du projet déclenche un wait-for-database dès qu'il détecte php/bin/console/frankenphp et que DATABASE_URL est défini (et il l'est : .env est embarqué dans l'image). Sans cet override, un docker run kirexo-prod bin/console about se bloquerait 60 s à attendre une Postgres absente du runner CI. Pour la même raison, on n'utilise pas bin/console about : la commande exigerait APP_SECRET (obligatoire au boot du framework en prod), absent du runner CI sans injection d'un secret factice. Un class_exists suffit pour vérifier la chargeabilité.
Effet en cas d'échec : si l'une des deux commandes sort non-zéro, le job échoue. Sur tag, jambe amd64 : docker:manifest-prod ne tourne pas : les références :$CI_COMMIT_TAG et :latest ne sont pas créées, et la chaîne tag → release est interrompue avant que la production ne puisse pull l'image cassée. Jambe arm64 : le signal KIREXO_PROD_ARM64_BUILT n'est jamais écrit, et la release sort en linux/amd64 seul. Dans les deux cas, le tag d'architecture de la jambe (:$CI_COMMIT_TAG-<arch>) est déjà poussé à ce stade : il reste dans le registry, intermédiaire et non installable ; un -arm64 ainsi laissé n'entre pas dans l'index et n'est pas signé. En MR, le tag mobile :php8.5-alpine est déjà poussé ; la prochaine exécution du job l'écrasera.
Construction multi-architecture de kirexo-prod (tag uniquement)¶
Sur une pipeline de tag, kirexo-prod est construite nativement sur deux runners, une jambe par architecture, puis les images sont assemblées en un index OCI. La jambe amd64 est obligatoire ; la jambe arm64 est best-effort : si elle échoue ou ne démarre pas (quota de minutes du runner hébergé épuisé, par exemple), l'index ne contient que linux/amd64 et la note de release le signale. Les pipelines de MR ne sont pas concernées : docker:build-prod y reste un build amd64 seul, sans index ni signature. Sur main, docker:build-prod n'est pas créé. Le raisonnement (natif plutôt qu'émulation, tag seulement) est dans Pourquoi une image multi-architecture, et comment elle reste vérifiable.
docker:build-prod (amd64, obligatoire) ─┐
├─> docker:manifest-prod ─┬─> docker:sign-prod
docker:build-prod-arm64 (arm64, allow_failure) ─┘ ├─> release:sbom
├─> release:bundle-render
├─> release:bundle-publish
├─> release:create
├─> release:links-arm64
├─> docker:test-install
├─> docker:test-install-traefik
└─> container_scanning (optional)
docker:build-prod-arm64 transmet à docker:manifest-prod le dotenv prod-arm64.env (KIREXO_PROD_ARM64_BUILT=true), publié seulement si la jambe a tout réussi. docker:manifest-prod transmet à ses consommateurs le dotenv manifest-prod.env (digests et KIREXO_PROD_ARM64_BUILT). Un dotenv ne se propage pas en cascade : chaque consommateur cite son producteur dans needs, avec artifacts: true.
Invariants de publication sur tag :
| # | Invariant | Où il est tenu |
|---|---|---|
| 1 | Chaque jambe ne pousse que kirexo-prod:$CI_COMMIT_TAG-<arch>. Aucune ne pousse :$CI_COMMIT_TAG, :latest ni :php8.5-alpine. |
Push conditionnel du script partagé. |
| 2 | Les trois références publiques sont créées en une opération, par docker:manifest-prod, qui ne tourne que si la jambe amd64 est verte. Elles pointent le même digest d'index. |
needs et contrôles de docker:manifest-prod. |
| 3 | L'index contient exactement les plateformes attendues : linux/amd64 seul, ou linux/amd64 et linux/arm64 si la jambe arm64 a publié KIREXO_PROD_ARM64_BUILT=true. arm64 n'est jamais déduit de la présence d'un tag -arm64 dans le registry. |
--provenance=false au build ; signal dotenv ; contrôle de docker:manifest-prod. |
| 4 | La signature porte sur le digest de l'index, avec --recursive : l'index et chaque image de plateforme sont signés. |
docker:sign-prod. |
| 5 | Garde-fou et smoke test HTTP s'exécutent sur chaque architecture, avant tout push. Un échec sur amd64 empêche la publication de la version ; un échec sur arm64 retire arm64 de la release, qui sort en linux/amd64 seul avec une section « Architecture » dans sa note. |
Script partagé ; allow_failure: true de docker:build-prod-arm64 ; release:create. |
| 6 | Les fichiers et liens linux/amd64 sont exigés sans condition (échec fermé) ; ceux de linux/arm64 seulement si KIREXO_PROD_ARM64_BUILT=true. |
docker:sign-prod, release:sbom, release:bundle-render, release_bundle_assets, release:links-arm64. |
Script partagé par les deux jambes¶
docker:build-prod déclare son script sous l'ancre YAML &kirexo-prod-image-script, et docker:build-prod-arm64 le reprend par script: *kirexo-prod-image-script. Le script reste une liste littérale : toute modification s'applique aux deux jambes. Seule la variable KIREXO_PROD_ARCH diffère :
| Job | KIREXO_PROD_ARCH |
|---|---|
docker:build-prod |
amd64 |
docker:build-prod-arm64 |
arm64 |
KIREXO_PROD_ARCH est l'architecture attendue de l'image construite. Les variables du job se fusionnent avec celles de .docker_job (DOCKER_TLS_CERTDIR, DOCKER_BUILDKIT restent hérités).
Ordre du script :
| # | Étape | Détail |
|---|---|---|
| 1 | Pull des caches | $KIREXO_BASE_IMAGE, $KIREXO_PROD_IMAGE et $CI_REGISTRY_IMAGE/kirexo-prod:latest, chacun suivi de \|\| true. |
| 2 | docker build |
--pull --provenance=false, trois --cache-from (les trois images ci-dessus), --build-arg BUILDKIT_INLINE_CACHE=1, --target frankenphp_prod, --tag $KIREXO_PROD_IMAGE. |
| 3 | Contrôle d'architecture | Compare l'architecture de l'image construite à KIREXO_PROD_ARCH. |
| 4 | Garde-fou | sh infra/image/check-prod-image.sh "$KIREXO_PROD_IMAGE". |
| 5 | Smoke test HTTP | sh infra/image/smoke-prod-image.sh "$KIREXO_PROD_IMAGE". |
| 6 | Push conditionnel | Sur tag : docker tag puis docker push de $CI_REGISTRY_IMAGE/kirexo-prod:$CI_COMMIT_TAG-$KIREXO_PROD_ARCH. Hors tag : docker push $KIREXO_PROD_IMAGE. |
| 7 | Smoke-tests post-push | composer check-platform-reqs et class_exists('App\\Kernel') sur l'image locale. |
| 8 | Signal de construction | Dernière entrée du script : écrit prod-$KIREXO_PROD_ARCH.env, une ligne KIREXO_PROD_<ARCH>_BUILT=true (<ARCH> = KIREXO_PROD_ARCH en majuscules). N'est atteinte que si toutes les étapes précédentes ont réussi. |
Signal de construction. Les deux jambes partagent le même script : l'écriture du fichier est donc inconditionnelle, mais seule docker:build-prod-arm64 le déclare en artifacts: reports: dotenv: (prod-arm64.env). Le fichier prod-amd64.env de la jambe amd64, comme celui des builds de MR, n'est publié nulle part. Un job en échec ne publie pas son dotenv (les artifacts sont publiés on_success par défaut) : KIREXO_PROD_ARM64_BUILT est alors absente pour docker:manifest-prod, ce qui vaut « pas d'arm64 ». Ces artifacts ne doivent jamais passer en when: always.
set -eu
arch_upper="$(printf '%s' "${KIREXO_PROD_ARCH:?KIREXO_PROD_ARCH non défini}" | tr '[:lower:]' '[:upper:]')"
printf 'KIREXO_PROD_%s_BUILT=true\n' "$arch_upper" > "prod-$KIREXO_PROD_ARCH.env"
echo "Signal écrit : prod-$KIREXO_PROD_ARCH.env (KIREXO_PROD_${arch_upper}_BUILT=true)."
Contrôle d'architecture. Placé après le build, avant le garde-fou et tout push :
built_arch="$(docker image inspect --format '{{.Architecture}}' "$KIREXO_PROD_IMAGE")"
if [ "$built_arch" != "${KIREXO_PROD_ARCH:?KIREXO_PROD_ARCH non défini}" ]; then
echo "Image construite en $built_arch, jambe attendue $KIREXO_PROD_ARCH : runner mal routé." >&2
exit 1
fi
echo "Architecture de l'image : $built_arch (attendue : $KIREXO_PROD_ARCH)."
Il empêche une jambe arm64 routée par erreur sur un runner amd64 de pousser une image amd64 étiquetée -arm64. Échec fermé si KIREXO_PROD_ARCH n'est pas défini.
--provenance=false. Sans ce flag, BuildKit ajoute à l'image poussée un manifeste d'attestation de plateforme unknown/unknown. L'index contiendrait alors plus que les deux plateformes attendues, et chaque référence d'architecture serait elle-même un index, hors du périmètre de la signature récursive.
Cache :latest. Après un tag, kirexo-prod:latest est un index multi-architecture : c'est la seule source de cache de la jambe arm64. kirexo-base n'existe qu'en amd64, et :php8.5-alpine est réécrit en amd64 par les builds de MR. Sur un runner arm64, le pull d'une référence sans variante arm64 échoue et le || true l'absorbe : le build part alors sans ce cache.
Job docker:build-prod-arm64¶
| Caractéristique | Valeur |
|---|---|
| Stage | docker (hérité de .docker_job) |
| Image | docker:29 (héritée de .docker_job) |
| Runner | tags: [saas-linux-small-arm64] — runner arm64 hébergé par GitLab, seule taille arm64 disponible sur le plan Free (2 vCPU, 8 Go). Ce tags remplace default: tags: [kirexo-self] : c'est le seul job de la CI sur runner hébergé (cf. Runners). |
| Service | docker:29-dind avec command: ["--mtu=1400"]. services étant un tableau, il remplace celui de .docker_job : l'image dind y est recopiée. --mtu=1400 contourne les coupures réseau de DinD signalées par GitLab sur ses runners Arm. |
variables |
KIREXO_PROD_ARCH: arm64 |
| Script | *kirexo-prod-image-script (cf. Script partagé). |
| Tag poussé | $CI_REGISTRY_IMAGE/kirexo-prod:$CI_COMMIT_TAG-arm64 |
needs: |
Aucun. Comme docker:build-prod, la jambe suit l'ordre des stages : sur tag, elle attend quality:composer-audit. |
| Déclencheur | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ uniquement. Ne référence pas .rules:docker, qui la rendrait manuelle en MR et sur main. |
allow_failure |
true : une jambe arm64 rouge, ou jamais démarrée faute de minutes sur le runner hébergé (ci_quota_exceeded), ne bloque pas la release. Celle-ci sort en linux/amd64 seul. |
| Artifact | reports: dotenv: prod-arm64.env — KIREXO_PROD_ARM64_BUILT=true, écrit par la dernière étape du script partagé et publié seulement si la jambe a tout réussi. |
interruptible |
false (hérité de .docker_job). |
Job docker:manifest-prod¶
| Caractéristique | Valeur |
|---|---|
| Stage | docker (hérité de .docker_job, qui fournit le login registry et le plugin docker buildx de l'image docker:29). |
needs: |
docker:build-prod et docker:build-prod-arm64 avec artifacts: true, pour recevoir le dotenv prod-arm64.env. Une jambe arm64 en échec, tolérée par allow_failure, ne bloque pas ce job. |
| Déclencheur | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ uniquement. |
| Références créées | $CI_REGISTRY_IMAGE/kirexo-prod:$CI_COMMIT_TAG, $CI_REGISTRY_IMAGE/kirexo-prod:latest, $KIREXO_PROD_IMAGE (kirexo-prod:php8.5-alpine). |
| Artifact | reports: dotenv: manifest-prod.env. |
interruptible |
false (hérité de .docker_job). |
Sélection des sources : seule la valeur littérale true de KIREXO_PROD_ARM64_BUILT vaut présence d'arm64. Absente, vide, false, TRUE ou 1 valent linux/amd64 seul.
KIREXO_PROD_ARM64_BUILT |
Sources de l'index | Plateformes attendues |
|---|---|---|
true |
$repo:$CI_COMMIT_TAG-amd64, $repo:$CI_COMMIT_TAG-arm64 |
linux/amd64 + linux/arm64 (2 entrées) |
| toute autre valeur, ou absente | $repo:$CI_COMMIT_TAG-amd64 |
linux/amd64 (1 entrée) ; la trace affiche Jambe arm64 absente (KIREXO_PROD_ARM64_BUILT≠true) : index linux/amd64 seul. |
Assemblage, en une seule opération, à partir des tags d'architecture retenus ("$@") :
docker buildx imagetools create \
--tag "$repo:$CI_COMMIT_TAG" \
--tag "$repo:latest" \
--tag "$KIREXO_PROD_IMAGE" \
"$@"
$repo vaut $CI_REGISTRY_IMAGE/kirexo-prod. Avec une seule source, imagetools create produit quand même un index à une entrée (--prefer-index vaut true par défaut). Le script, en set -eu, contrôle ensuite l'index et échoue fermé :
| Contrôle | Message d'échec |
|---|---|
Le digest de :$CI_COMMIT_TAG est lisible. |
Digest de l'index <repo>:<tag> illisible. |
:latest et $KIREXO_PROD_IMAGE pointent le même digest que :$CI_COMMIT_TAG. |
<référence> pointe <digest> au lieu de l'index <digest>. |
L'index compte exactement les plateformes attendues : linux/amd64 toujours, linux/arm64 en plus si KIREXO_PROD_ARM64_BUILT=true. |
Index attendu : exactement linux/amd64 (vu : N entrée(s)). ou Index attendu : exactement linux/amd64 + linux/arm64 (vu : N entrée(s)). |
Sur succès, la trace affiche Index <digest> : suivi d'une ligne <os>/<arch> <digest> par plateforme.
Variables exportées dans manifest-prod.env :
| Variable | Présence | Contenu | Consommateurs |
|---|---|---|---|
KIREXO_PROD_INDEX_DIGEST |
toujours | Digest de l'index. | docker:sign-prod, docker:test-install |
KIREXO_PROD_AMD64_DIGEST |
toujours | Digest de l'image linux/amd64. |
docker:sign-prod, release:sbom |
KIREXO_PROD_ARM64_BUILT |
toujours | true si l'index contient linux/arm64, false sinon. |
docker:sign-prod, release:sbom, release:bundle-render, release:bundle-publish, release:create, release:links-arm64 |
KIREXO_PROD_ARM64_DIGEST |
seulement si KIREXO_PROD_ARM64_BUILT=true |
Digest de l'image linux/arm64. |
docker:sign-prod, release:sbom |
Le nom du job et ceux de ces variables sont des contrats consommés par d'autres jobs : les renommer impose de modifier leurs consommateurs dans le même changement. Chaque consommateur cite docker:manifest-prod dans ses needs avec artifacts: true : un dotenv ne se transmet pas en cascade.
Ne jamais définir KIREXO_PROD_ARM64_BUILT en variable CI/CD
Les variables de projet, de groupe et de pipeline (lancement manuel, planifié ou par API) l'emportent sur celles d'un dotenv. Définir KIREXO_PROD_ARM64_BUILT dans Settings › CI/CD › Variables ou au lancement d'une pipeline court-circuite le signal de la jambe arm64 et celui de docker:manifest-prod. Forcée à true alors que kirexo-prod:<tag>-arm64 n'existe pas, elle fait échouer docker buildx imagetools create (échec fermé) ; forcée à une autre valeur, elle retire arm64 de toutes les releases.
Durées¶
Le chemin multi-architecture ne s'exécute que sur tag : aucune durée n'est encore relevée. La durée de chaque job se lit dans la trace de la pipeline de tag. Éléments structurels :
- les deux jambes tournent en parallèle : la durée murale du stage est celle de la jambe la plus longue, plus
docker:manifest-prod, qui ne fait que des opérations sur le registry ; - la jambe arm64 n'a pas de cache
kirexo-base: les couches du stagefrankenphp_base(extensions PHP) y sont recompilées à chaque tag. Seules les couches déjà présentes danskirexo-prod:latestarm64 sont réutilisées.
Ce qui ne se prouve qu'à la première pipeline de tag
docker:build-prod-arm64, docker:manifest-prod et la signature récursive n'existent dans aucune pipeline de MR : la validation de configuration (castor ci:local) et les gardes de tests/Unit/Infra/ ne remplacent pas une exécution réelle. Restent à constater dans les traces de la première pipeline de tag qui les exécute :
docker:build-prod-arm64tourne sur un runner arm64 (Architecture de l'image : arm64 (attendue : arm64).), garde-fou et smoke test HTTP verts, et sa dernière ligne estSignal écrit : prod-arm64.env (KIREXO_PROD_ARM64_BUILT=true).;- le contournement
--mtu=1400suffit : pas dedocker push,apk addoucomposer installfigé puis sorti en timeout ; - une jambe arm64 en échec ou jamais démarrée ne bloque pas
docker:manifest-prod; docker:manifest-prodaffiche un index de deux entrées avec arm64, ouJambe arm64 absente…et une entrée sans ;docker:sign-prodaffiche sept lignes✓ signature vérifiéeavec arm64, cinq sans ;release:sbomproduit quatre fichiers avec arm64, deux sans, etrelease:bundle-publishen envoie sept ou cinq ;docker:test-installest vert, son artifact contientvar/install-e2e/footprint.mdet pas de.env, etrelease:bundle-publishne démarre qu'après lui ;docker:test-install-traefikest vert (T1 à T5), son artifactvar/install-e2e-traefik/ne contient pas de.env, etrelease:bundle-publishne démarre qu'après lui ;container_scanningdémarre aprèsdocker:manifest-prod, et la plateforme retenue par Trivy sur l'index ;- la release porte quatre liens SBOM avec arm64 (deux posés par
release:links-arm64), deux sans, téléchargeables sans jeton ; sans arm64, sa note contient la section « Architecture » ; docker buildx imagetools inspectsurkirexo-prod:<version>, sans authentification, liste les plateformes publiées, et la commandecosign verifyde Déployer Kirexo en production passe ;- la durée de chaque jambe, et le coût en minutes de calcul du runner arm64.
Une jambe amd64 en échec laisse la version sans référence publique : corriger, puis poser un nouveau tag de correctif. Une jambe arm64 en échec publie la version en linux/amd64 seul.
Règles de déclenchement dédiées de docker:build-docs¶
Contrairement à docker:build-base et docker:build-prod (qui référencent .rules:docker), docker:build-docs porte ses propres rules:. Ordre des règles (la première qui matche gagne) :
| Contexte | Condition | Déclenchement |
|---|---|---|
main, mkdocs/Dockerfile modifié |
$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CREATE_TAG != "true" + changes: [mkdocs/Dockerfile] |
Automatique (when: on_success). |
main, sans modif du Dockerfile |
$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CREATE_TAG != "true" |
Manuel (bouton ▶, allow_failure: true). |
| Merge Request | $CI_PIPELINE_SOURCE == "merge_request_event" |
Manuel (bouton ▶, allow_failure: true). |
| Tag | $CI_COMMIT_TAG |
Automatique (when: on_success) — l'image alimente pages. |
La règle « main + modif du Dockerfile » est placée avant la règle « main » générique : comme GitLab retient la première règle qui matche, l'ordre garantit que le rebuild automatique l'emporte sur le manuel dès que mkdocs/Dockerfile change. Les deux règles main portent la garde $CREATE_TAG != "true" pour ne pas se déclencher dans la pipeline isolée de création de tag.
kirexo-docs:latest est l'environnement de build de la doc, consommé par le job pages sur tag. Le rebuild automatique sur main à chaque évolution de mkdocs/Dockerfile garantit que le prochain déploiement pages (sur tag) part d'une image à jour, sans intervention manuelle.
Bootstrap initial obligatoire — sauf pour la doc
Avant le premier passage de la CI, les images kirexo-base et kirexo-dev doivent exister dans le registry, sinon tous les jobs PHP/E2E échouent immédiatement sur ErrImagePull. docker:build-base se débloque par son bouton ▶ (needs: []). docker:build-dev, lui, ne part qu'après des stages quality et test verts, impossibles sans kirexo-dev : l'image dev se construit et se pousse une première fois depuis l'hôte. Procédure : Bootstrapper la pipeline CI, étape 6.
Les images kirexo-docs et kirexo-supply-chain n'ont pas besoin de ce bootstrap manuel : sur tag, docker:build-docs et docker:build-supply-chain (stage docker) tournent automatiquement avant leurs consommateurs respectifs du stage release (pages pour la doc, docker:sign-prod et release:sbom pour la supply chain) — les images sont donc toujours fraîches au moment où ces jobs s'exécutent.
Image supply chain (docker:build-supply-chain)¶
L'image kirexo-supply-chain embarque les binaires officiels cosign et syft sur une base Alpine 3.22 (cf. supply-chain/Dockerfile). Elle est consommée par docker:sign-prod (signature keyless de kirexo-prod) et release:sbom (génération SPDX + CycloneDX). Les motivations de cette image custom sont détaillées dans Pourquoi une image custom kirexo-supply-chain — en résumé : les images officielles upstream sont distroless (pas de sh), incompatibles avec le wrapper sh -c "step_script" du GitLab Runner SaaS.
| Caractéristique | Valeur |
|---|---|
| Stage | docker |
| Base | alpine:3.22. |
| Outils embarqués | cosign et syft, copiés depuis les images upstream via un multi-stage Docker : FROM gcr.io/projectsigstore/cosign:<tag> AS cosign-stage et FROM anchore/syft:<tag> AS syft-stage, puis COPY --from=cosign-stage /ko-app/cosign /usr/local/bin/cosign et COPY --from=syft-stage /syft /usr/local/bin/syft. Les versions vivent dans le tag des deux FROM source — pas d'ARG, pas de SHA256 manuel. |
| Surface minimale | Pas de curl, pas de tar : les binaires arrivent par COPY --from=, aucun outil de download n'a besoin d'être installé puis supprimé. Seul ca-certificates est ajouté (requis par cosign à l'exécution pour Fulcio / Rekor en HTTPS). |
| Chaîne de confiance | Héritée des registries source : gcr.io/projectsigstore (Sigstore publie ses propres images cosign) et Docker Hub anchore/syft (Anchore publie ses propres images syft). Pas de vérification SHA256 manuelle — c'est le même modèle de confiance que n'importe quel FROM du Dockerfile racine. |
needs: |
[] — détaché du DAG, comme docker:build-docs. |
| Smoke-test post-push | docker run --rm $KIREXO_SUPPLY_CHAIN_IMAGE cosign version et ... syft version — valide l'image fraîchement poussée avant qu'un job de release ne s'y appuie. Le Dockerfile fait déjà ce check au build (RUN cosign version && syft version) ; le run sur l'image pushed valide aussi l'environnement d'exécution (PATH, permissions, libs dynamiques). |
| Tag poussé | $CI_REGISTRY_IMAGE/kirexo-supply-chain:latest (tag unique — pas de versionnement de l'image elle-même). |
Règles de déclenchement¶
Identiques à celles de docker:build-docs (ordre des règles : la première qui matche gagne) :
| Contexte | Condition | Déclenchement |
|---|---|---|
main, supply-chain/Dockerfile modifié |
$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CREATE_TAG != "true" + changes: [supply-chain/Dockerfile] |
Automatique (when: on_success). |
main, sans modif du Dockerfile |
$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CREATE_TAG != "true" |
Manuel (bouton ▶, allow_failure: true). |
| Merge Request | $CI_PIPELINE_SOURCE == "merge_request_event" |
Manuel (bouton ▶, allow_failure: true). |
| Tag | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ |
Automatique (when: on_success) — l'image alimente docker:sign-prod et release:sbom. |
Bumper cosign ou syft¶
Le bump est automatique via Renovate : les versions vivent dans le tag des deux FROM du supply-chain/Dockerfile, suivis nativement par le manager dockerfile de Renovate (cf. Configurer les montées de version automatiques (Renovate)). À chaque nouvelle release upstream, Renovate ouvre une MR qui édite le tag du FROM concerné ; au merge, docker:build-supply-chain rebuild automatiquement l'image (règle changes: [supply-chain/Dockerfile]).
Bump manuel équivalent si nécessaire (urgence sécurité avant que Renovate ne tourne, par exemple) : éditer le tag du FROM ciblé dans supply-chain/Dockerfile (FROM gcr.io/projectsigstore/cosign:<tag> ou FROM anchore/syft:<tag>), commit, push sur main — l'effet est identique.
Cache des couches Docker¶
Chaque job de build pull l'image précédente du registry (docker pull ... || true) avant de builder, puis passe les images comme --cache-from. Le flag BUILDKIT_INLINE_CACHE=1 incorpore les métadonnées de cache dans l'image poussée, ce qui rend le cache exploitable d'un job à l'autre : il est relu depuis l'image du registry, pas depuis l'état local du démon Docker (sans ce flag, BuildKit recommence du FROM à chaque build).
Signature keyless de kirexo-prod (docker:sign-prod)¶
Sur tag de release, le job docker:sign-prod signe l'index assemblé par docker:manifest-prod (linux/amd64, plus linux/arm64 si présent), avec cosign en mode keyless (sigstore). Pas de clé privée à gérer côté CI ni côté projet : l'authenticité du signataire est attestée par le pipeline GitLab lui-même via OIDC.
| Caractéristique | Valeur |
|---|---|
| Stage | docker |
| Image | $KIREXO_SUPPLY_CHAIN_IMAGE (image custom Alpine + cosign + syft, cf. Image supply chain). Pas d'override d'entrypoint nécessaire — l'image embarque déjà sh. |
needs: |
docker:manifest-prod avec artifacts: true (strict — le dotenv manifest-prod.env fournit les digests et KIREXO_PROD_ARM64_BUILT ; l'index n'existe qu'après le manifeste, avec une jambe (amd64) ou deux (amd64 + arm64), et signer un digest absent du registry échouerait en manifest unknown) et docker:build-supply-chain avec artifacts: false (strict — sans cette image, le job n'a pas de binaire cosign). |
id_tokens.SIGSTORE_ID_TOKEN.aud |
sigstore — audience attendue par Fulcio pour accepter le JWT OIDC émis par GitLab. |
COSIGN_YES |
true — désactive l'invite interactive (sécurité ceinture-bretelles avec --yes). |
| Déclencheur | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ uniquement. Les builds de MR ne sont pas livrés en prod — les signer polluerait le log de transparence. |
interruptible |
false — l'attestation publiée dans Rekor est immuable ; une coupure mi-job laisserait une trace orpheline. |
| Variables CI/CD à provisionner | Aucune nouvelle. CI_REGISTRY_USER/CI_REGISTRY_PASSWORD (déjà injectés par GitLab) servent au cosign login ; le JWT OIDC est généré automatiquement par GitLab via la directive id_tokens. |
| Consommateurs | release:bundle-publish et release:create l'attendent par needs : ni paquet ni release sans image signée. |
Le script, en set -eu, exige d'abord KIREXO_PROD_INDEX_DIGEST et KIREXO_PROD_AMD64_DIGEST, et échoue si l'une manque. KIREXO_PROD_ARM64_DIGEST n'est exigée que si KIREXO_PROD_ARM64_BUILT=true. Il enchaîne ensuite deux temps :
1. Une signature, par digest, récursive.
$repo vaut $CI_REGISTRY_IMAGE/kirexo-prod. La signature porte sur le digest de l'index, jamais sur un tag mutable. --recursive signe l'index et chacune des images de plateforme qu'il référence. Toutes les références publiées sont couvertes :
| Référence | Pointe | Couverte par |
|---|---|---|
kirexo-prod:$CI_COMMIT_TAG |
l'index | la signature de l'index |
kirexo-prod:latest |
l'index | la signature de l'index |
kirexo-prod:php8.5-alpine ($KIREXO_PROD_IMAGE) |
l'index | la signature de l'index |
kirexo-prod:$CI_COMMIT_TAG-amd64, kirexo-prod@$KIREXO_PROD_AMD64_DIGEST |
l'image linux/amd64 |
la signature récursive de l'image enfant |
kirexo-prod:$CI_COMMIT_TAG-arm64, kirexo-prod@$KIREXO_PROD_ARM64_DIGEST — si KIREXO_PROD_ARM64_BUILT=true |
l'image linux/arm64 |
la signature récursive de l'image enfant |
Un kirexo-prod:$CI_COMMIT_TAG-arm64 poussé par une jambe tombée après son push n'est pas dans l'index : il n'est ni signé, ni vérifié.
2. Post-vérification. La CI rejoue cosign verify sur ces références — cinq sans arm64, sept avec —, avec l'identité et l'émetteur qu'utilise le consommateur (cf. Vérifier une signature côté consommateur). Chaque référence vérifiée produit une ligne ✓ signature vérifiée : <référence> ; une seule référence non vérifiable fait échouer le job. Sans arm64, la trace affiche en plus Index linux/amd64 seul (KIREXO_PROD_ARM64_BUILT≠true) : aucune référence arm64 à vérifier.
Stockage des signatures dans le registry GitLab
cosign stocke les signatures dans le registry, à côté des images signées. --recursive n'ajoute que des signatures de même nature sur les digests des images enfants : aucun mode de stockage particulier n'est configuré. La post-vérification constate, à chaque tag, que les cinq ou sept références se vérifient.
Chaîne de confiance keyless¶
Le mode keyless dématérialise la PKI : aucune clé privée n'est conservée par Kirexo. À chaque signature, cosign enchaîne trois échanges réseau avec l'infra publique sigstore :
| Acteur | Rôle |
|---|---|
| GitLab CI | Émet un JWT OIDC court-vivant pour le job (id_tokens.SIGSTORE_ID_TOKEN, audience sigstore). Le JWT contient l'identité du pipeline : URL du projet, refs, claims sub du type https://gitlab.com/<group>/<project>//.gitlab-ci.yml@refs/tags/<tag>. |
| Fulcio (CA publique sigstore) | Reçoit le JWT, le vérifie auprès du provider OIDC GitLab, et émet en retour un certificat X.509 éphémère (validité ~10 min) lié à cette identité. Aucune clé privée à long terme n'est jamais matérialisée — la clé est générée à la volée par cosign dans le runner, le cert est révoqué à l'expiration. |
| Rekor (log de transparence) | Reçoit la signature + le certificat Fulcio et publie une entrée immuable dans le log de transparence public. C'est cette entrée qui permet à un vérificateur (cf. ci-dessous) d'attester a posteriori qu'une signature a bien été produite par ce pipeline, à ce moment. |
Côté Kirexo, la seule maintenance possible est de monter cosign en version majeure suivante (v3 quand il sortira). Le binaire cosign est embarqué dans l'image custom kirexo-supply-chain via un COPY --from=gcr.io/projectsigstore/cosign:<tag> du supply-chain/Dockerfile (cf. Image supply chain) — le manager dockerfile natif de Renovate suit ce tag automatiquement et ouvre la MR de bump à chaque release upstream.
Vérifier une signature côté consommateur¶
cosign verify $CI_REGISTRY_IMAGE/kirexo-prod:$TAG \
--certificate-identity-regexp='^https://gitlab\.com/shaurifr/kirexo' \
--certificate-oidc-issuer='https://gitlab.com'
Sur succès, cosign affiche les claims OIDC capturés par Fulcio (identité du pipeline, ref, sha du commit) et le hash de l'entrée Rekor associée — la chaîne de confiance remonte jusqu'au pipeline GitLab du tag.
Sur un tag de version, la commande vérifie l'index. Une image de plateforme se vérifie par son digest, $CI_REGISTRY_IMAGE/kirexo-prod@sha256:…, avec les mêmes options : c'est la référence que tire un hôte de cette architecture.
La procédure côté serveur de production est documentée dans Vérifier la signature de l'image avant de la pull.
Stage maintenance¶
Le stage maintenance regroupe les jobs périodiques et non bloquants : le SAST informatif et les jobs de cron. Son nom reflète son rôle — « périodique / maintenance » — et non « tout ce qui touche la sécurité ». Le garde-fou de sécurité bloquant, lui, est quality:composer-audit (stage quality, voir Job quality:composer-audit).
Les jobs sont répartis sur deux fichiers d'inclusion. Les noms de fichiers (.gitlab/ci/security.yml) et de jobs (security:composer-audit) conservent volontairement le préfixe « security » — ils restent regroupés par thème ; seul le stage s'appelle désormais maintenance.
| Fichier | Jobs |
|---|---|
.gitlab/ci/security.yml |
sast (umbrella neutralisé), semgrep-sast, secret_detection, security:secret-gate, container_scanning, security:container-issue, container_scanning:builders, security:container-issue:builders, security:composer-audit. |
.gitlab/ci/dependencies.yml |
dependencies:renovate, tools:version-check. |
Les sources de pipeline qui déclenchent ces jobs diffèrent : MR/main pour le SAST et la Secret Detection (+ son gate), schedule pour l'audit Composer, Renovate, le version-check et les scans CVE d'images builders. container_scanning et security:container-issue (image kirexo-prod) ont deux déclencheurs : schedule (scan quotidien de kirexo-prod:latest) et tag de release semver (scan de l'image kirexo-prod:$CI_COMMIT_TAG fraîchement poussée — signal CVE au moment de la release, non H+24). Les jobs builders (container_scanning:builders / security:container-issue:builders), eux, ne tournent qu'en cron : ils scannent les images qui alimentent la chaîne de build CI, pas un livrable de release.
L'audit Composer bloquant vit dans le stage quality, pas ici
Le job quality:composer-audit (.gitlab/ci/quality.yml, stage quality) audite composer.lock de façon bloquante sur chaque MR, main et tag — il fait partie des vérifications qualité, pas du stage maintenance. Voir Job quality:composer-audit. Le security:composer-audit documenté ci-dessous est, lui, le cron quotidien du stage maintenance qui ouvre une issue.
Job semgrep-sast¶
Hérité du template natif Security/SAST.gitlab-ci.yml. GitLab détecte automatiquement le langage du projet (PHP) et lance l'analyseur Semgrep correspondant (semgrep-sast). Le rapport JSON produit est exposé dans l'onglet Security de la MR. Le job parent « umbrella » sast du template est neutralisé (rules: - when: never) — il ne sert qu'à la configuration.
| Caractéristique | Valeur |
|---|---|
| Stage | maintenance (override — le template par défaut place l'analyseur dans le stage test). |
needs: |
[] — détaché du DAG. Le job démarre dès le début de la pipeline sur une MR, sans attendre quality/test. Comme il est non bloquant (allow_failure: true), autant l'avoir tôt sans freiner les vérifications bloquantes. |
allow_failure |
true — informatif. Un finding SAST ne bloque jamais le merge. |
| Déclencheurs | $CI_PIPELINE_SOURCE == "merge_request_event" ou $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH, jamais si $CREATE_TAG == "true". |
interruptible |
true — annulé automatiquement si un nouveau commit arrive sur la même MR / branche. |
| Exclusions de scan | SAST_EXCLUDED_PATHS : vendor, node_modules, var, public/assets, site, .phpunit.cache. Évite le bruit sur les dossiers générés ou vendor. |
L'override des règles exclut la pipeline de création de tag ($CREATE_TAG == "true") : sans elle, le template GitLab par défaut ferait tourner SAST dans cette pipeline isolée, ce qui n'a pas de sens (le commit n'a pas changé, le SAST a déjà tourné sur la MR qui a produit ce commit).
Job security:composer-audit¶
Audit quotidien des dépendances Composer contre la base packagist/security-advisories. Hérite de .php_quality_job (image kirexo-base, pas de services Postgres/Redis nécessaires).
Stratégie MR-first / fallback issue : le job tente d'abord d'ouvrir une merge request de patch (composer update --with-all-dependencies ciblé sur les packages vulnérables), et retombe sur une simple issue d'alerte si l'update ne suffit pas.
| Caractéristique | Valeur |
|---|---|
| Stage | maintenance |
| Image | KIREXO_BASE_IMAGE (via .php_quality_job), avec jq installé en before_script. |
| Déclencheur | $CI_PIPELINE_SOURCE == "schedule" uniquement — nécessite une schedule manuellement créée (cf. Configurer l'audit de sécurité quotidien). |
GIT_DEPTH |
0 — git push refuse de pousser une branche depuis un repo en « shallow update not allowed ». |
interruptible |
false — un audit lancé n'est pas annulé même si un nouveau commit arrive. |
| Artifact | audit-composer.json, conservé 1 mois (when: always). |
| Token requis | GITLAB_TOKEN, scopes api + write_repository. Le scope write_repository est requis pour pousser la branche security/composer-* ; le scope api couvre l'ouverture de MR et d'issue. |
| Identité du commit | ci-bot@kirexo.app (Kirexo CI Bot) — bot dédié pour ne pas polluer git log avec un nom humain. |
| Push CI-skip | git push -o ci.skip — la pipeline tournera au merge de la MR, pas à l'ouverture (qui la déclenche déjà via l'événement MR). |
| Labels (MR ou issue) | security, dependencies |
Cinématique¶
Le script enchaîne :
- Audit initial —
composer audit --no-interaction --format=json > audit-composer.json. Le code retour est lu à la main (set +e) pour distinguer « rien à faire » de « vulnérable » et de « audit cassé ». - Court-circuit dédup MR — interroge
GET /projects/:id/merge_requests?state=opened&labels=security,dependenciesfiltré sursource_branchpréfixée parsecurity/composer-. Si une MR de patch est déjà ouverte, le job sort en0sans créer de doublon (le cron quotidien ne refait pas la même MR tant qu'elle n'est pas mergée). - Tentative d'update —
composer update --no-interaction --with-all-dependencies $VULN_PACKAGES, où$VULN_PACKAGESest la liste dédupliquée extraite du rapport.--with-all-dependenciesremonte les transitives nécessaires pour satisfaire les nouvelles contraintes. - Ré-audit —
composer audit --no-interaction --lockedaprès l'update. S'il repasse, la voie MR est ouverte ; sinon, fallback issue.
Tableau des cas¶
| Cas | Détection | Effet |
|---|---|---|
| Aucune vulnérabilité | composer audit retourne 0. |
Le job passe, aucun appel API. |
| MR de patch déjà ouverte | Réponse API non vide à la requête de dédup. | Le job log « on ne duplique pas » et sort en 0. |
| Update suffit à corriger | composer update réussit et ré-audit clean. |
Push d'une branche security/composer-YYYYMMDD-HHMMSS puis POST /projects/:id/merge_requests (labels: security,dependencies, remove_source_branch: true, squash: true). Titre : Patch sécurité Composer du YYYY-MM-DD. Le job termine en 0. |
| Update insuffisant ou en conflit | composer update échoue ou ré-audit toujours rouge (versions patchées hors des contraintes composer.json, conflit de resolver). |
Fallback : POST /projects/:id/issues listant les packages, versions affectées, titres et CVE. Labels security,dependencies. Le job termine en exit 1 pour rester visible en rouge. |
| Audit cassé | Code retour ≠ 0 et JSON non exploitable (réseau, packagist HS, composer.lock corrompu). |
Aucune issue ni MR créée (jq -e '.advisories \| type == "object"' échoue avant tout appel API). Le job échoue avec le code de sortie de composer audit. |
Diagramme¶
flowchart TD
A[composer audit] -->|exit 0| Z[Job vert - rien à faire]
A -->|exit ≠ 0, JSON cassé| ERR[Job échoue - aucun appel API]
A -->|exit ≠ 0, JSON OK| B{MR security/composer-*<br/>déjà ouverte ?}
B -->|oui| Z2[Job vert - dédup]
B -->|non| C[composer update --with-all-dependencies]
C -->|update KO| F[Fallback issue]
C -->|update OK| D[composer audit --locked]
D -->|toujours vulnérable| F
D -->|clean| E[Push branche security/composer-*<br/>+ POST merge_requests]
F -->|POST issues| FX[Job rouge - alerte humaine]
E --> EX[Job vert - MR ouverte]
Voir Configurer l'audit de sécurité quotidien pour la procédure de création de la schedule.
Job dependencies:renovate¶
Lance Renovate en mode self-hosted contre le seul dépôt Kirexo. Renovate ouvre automatiquement des merge requests de montée de version (Composer, npm, images Docker, jobs CI) et des MRs de sécurité prioritaires. La configuration vit dans renovate.json à la racine — voir Configurer les montées de version automatiques (Renovate).
| Caractéristique | Valeur |
|---|---|
| Stage | maintenance (défini dans .gitlab/ci/dependencies.yml). |
| Image | renovate/renovate:43 (tag majeur épinglé, pas :latest — Renovate suit son propre tag via le manager gitlabci). |
| Déclencheur | $CI_PIPELINE_SOURCE == "schedule" uniquement. |
interruptible |
false. |
| Variables clés | RENOVATE_PLATFORM: gitlab, RENOVATE_ENDPOINT: $CI_API_V4_URL, RENOVATE_TOKEN: $GITLAB_TOKEN, RENOVATE_AUTODISCOVER: "false", RENOVATE_REPOSITORIES: $CI_PROJECT_PATH. |
| Token requis | GITLAB_TOKEN — un Personal Access Token (les project access tokens sont réservés à Premium/Ultimate), scopes api + write_repository. Renovate le lit via le mapping RENOVATE_TOKEN: $GITLAB_TOKEN ; aucune variable RENOVATE_TOKEN distincte n'existe (cf. Variables CI/CD GitLab). Plus GITHUB_COM_TOKEN (PAT github.com read-only) : composer update et les release notes tapent l'API github.com. Ici le jeton est exigé — un préflight fait échouer le job s'il est vide ou refusé, sans quoi la MR de montée de version partirait avec un composer.lock non régénéré. |
RENOVATE_AUTODISCOVER: "false" + RENOVATE_REPOSITORIES: $CI_PROJECT_PATH cible explicitement ce dépôt : sans ça, Renovate scannerait tous les projets accessibles par le token.
Job tools:version-check¶
Surveille les versions épinglées par directive ARG dans le Dockerfile racine que Renovate ne détecte pas nativement (Node, Claude Code, Castor, glab) et ouvre une issue GitLab récapitulative si au moins un outil est en retard.
| Caractéristique | Valeur |
|---|---|
| Stage | maintenance (défini dans .gitlab/ci/dependencies.yml). |
| Image | KIREXO_BASE_IMAGE (via .php_quality_job) — même image que security:composer-audit, jq y est déjà embarqué (stage frankenphp_base du Dockerfile). |
| Déclencheur | $CI_PIPELINE_SOURCE == "schedule" uniquement. |
interruptible |
false. |
| Token requis | GITLAB_TOKEN (scope api suffit ici — pas de push de branche) — pour créer l'issue. Le même PAT que tag:create / security:composer-audit. |
| Labels d'issue créée | dependencies, tooling. |
| Anti-doublon | Avant d'ouvrir une issue, le job appelle castor ci:check-open-issue --labels="dependencies,tooling" : tant qu'une issue précédente avec ces deux labels reste ouverte, aucune nouvelle issue n'est créée. Sans ce garde-fou, le cron quotidien dupliquerait l'issue chaque jour tant que les outils restent en retard. Aligné avec le pattern de dédup MR de security:composer-audit. |
Le job extrait quatre directives ARG du Dockerfile, les compare aux dernières versions publiées et ouvre une issue listant ce qui est en retard.
ARG du Dockerfile |
Source de la dernière version | Particularité |
|---|---|---|
NODE_VERSION |
APKINDEX Alpine du paquet nodejs (repo main) de la branche ciblée par NODE_ALPINE_BRANCH : curl .../alpine/${NODE_ALPINE_BRANCH}/main/x86_64/APKINDEX.tar.gz \| tar -xzO APKINDEX \| awk sur le bloc P:nodejs exact (jamais nodejs-dev/-doc). On suit la version servie par Alpine, pas les releases nodejs.org — sinon on signalerait un faux drift dès que nodejs.org devance Alpine. |
Version Alpine complète (24.18.1-r0, révision -rN incluse) — plus de notion de « ligne majeure ». Installé via apk, intégrité garantie par l'index signé (pas de SHA-256 vérifié au build). |
CLAUDE_CODE_VERSION |
curl https://registry.npmjs.org/@anthropic-ai/claude-code puis jq '.["dist-tags"].latest'. Curl direct sur le registry npm pour ne pas avoir à embarquer Node (npm view) uniquement pour cette lecture. |
Sans préfixe. |
CASTOR_VERSION |
https://api.github.com/repos/jolicode/castor/releases/latest → .tag_name. Rate limit GitHub non authentifié (60/h) — suffisant pour un cron quotidien. |
Tag avec préfixe v (GitHub publie ses tags avec v) — le préfixe est conservé dans ARG pour respecter la sémantique d'origine. |
GLAB_VERSION |
https://gitlab.com/api/v4/projects/gitlab-org%2Fcli/releases?per_page=1 → .[0].tag_name. API GitLab publique, pas de token requis sur les projets publics. |
Sans préfixe (le v éventuel est strippé via sed). |
Tous les curl portent --retry 3 --retry-delay 2 --retry-connrefused pour absorber les blips transitoires des APIs publiques sans transformer le cron en faux positif (cf. plus bas).
Si une API renvoie une chaîne vide (panne réseau, registry HS, APKINDEX inaccessible), l'outil concerné est ignoré plutôt que faussement signalé comme « obsolète vers vide » — garde-fou contre les issues trompeuses. Si tous les outils restants sont à jour, le job passe sans créer d'issue. Sinon, l'issue suggère de jouer castor image:upgrade-tools pour appliquer le bump (version, plus le hash SHA-256 pour les binaires vérifiés Castor et glab ; Node — installé via apk — et Claude Code n'ont pas de hash managé). L'entrée Node de l'issue prend la forme Node : <épinglé> → <alpine> (Alpine <branche>).
Pourquoi une issue plutôt qu'une MR auto (contrairement à security:composer-audit)
Les binaires vérifiés (Castor, glab) apparient chaque ARG *_VERSION à un ARG *_SHA256 pour contrôler l'intégrité du binaire téléchargé au build. Calculer ce hash nécessite de télécharger le binaire dans un job dédié (un par outil vérifié). La cible Castor castor image:upgrade-tools fait déjà ce boulot côté dev (download + sha256sum + bump du Dockerfile + MR via glab), couverte par ToolsUpgraderTest. Reproduire cette logique en CI dupliquerait du code testé unitairement sans bénéfice. Workflow assumé : la CI ouvre l'issue, l'humain joue castor image:upgrade-tools en local, push la MR. (Node passe par apk et Claude Code par npm — ni l'un ni l'autre n'a de hash à recalculer.)
Jobs container_scanning et security:container-issue (image de production)¶
Scan des CVE OS / libs système de l'image de production (Trivy, hérité du template natif Jobs/Container-Scanning.gitlab-ci.yml). container_scanning produit le rapport ; security:container-issue le parse et ouvre une issue GitLab uniquement si au moins une CVE de sévérité Critical ou High est remontée. Non bloquants (allow_failure: true) — une CVE de base image n'arrête jamais une release.
Particularité : deux déclencheurs distincts, et l'image scannée diffère selon le contexte. La sélection se fait via rules:variables (chaque branche de rules: pose sa propre valeur de CS_IMAGE / IMAGE_REF).
| Déclencheur | CS_IMAGE scannée par container_scanning |
IMAGE_REF utilisée par security:container-issue |
|---|---|---|
Cron quotidien ($CI_PIPELINE_SOURCE == "schedule") |
$CI_REGISTRY_IMAGE/kirexo-prod:latest (image actuellement « courante » — implicitement celle déployée sauf rollback). |
latest (humanise le titre de l'issue). |
Tag de release ($CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/) |
$CI_REGISTRY_IMAGE/kirexo-prod:$CI_COMMIT_TAG (index linux/amd64, plus linux/arm64 si publié, fraîchement assemblé par docker:manifest-prod à la release). |
$CI_COMMIT_TAG. |
container_scanning porte needs: [{ job: docker:manifest-prod, optional: true, artifacts: false }]. Sur tag, il attend l'assemblage de l'index qu'il va scanner : kirexo-prod:$CI_COMMIT_TAG n'existe qu'après docker:manifest-prod. Dépendre d'une jambe ferait échouer le scan sur une référence encore absente, en silence puisque le job est allow_failure: true. Sur schedule, docker:manifest-prod est absent de la pipeline : le needs optionnel est satisfait par absence et le scan démarre sur :latest. Jusqu'au ticket #270, docker:build-prod, alors dépendance du scan, figurait en manual jamais joué sur le schedule, ce qui mettait container_scanning en skipped : le scan quotidien ne tournait pas.
Scan limité à une seule architecture
CS_IMAGE désigne un index, et Trivy le résout vers une plateforme (a priori linux/amd64, à confirmer dans la trace du scan d'un tag). L'image linux/arm64, quand elle est publiée, n'est pas scannée. Elle part des mêmes dépôts Alpine et du même apk upgrade, sans garantie de versions de paquets identiques. Limite assumée ; son SBOM linux/arm64 (cf. Job release:sbom) permet de la corréler aux CVE publiées dans un outil tiers.
security:container-issue ne casse jamais la pipeline (sort en 0). Si le rapport est absent (image inexistante, scan en échec), il log « rien à signaler » et termine. Sinon, il calcule un récap par sévérité (Critical / High / Medium / Low / Other / Total) et n'ouvre une issue que si Critical + High > 0. La liste détaillée dans le corps ne contient que les CVE Critical et High triées par sévérité décroissante ; les autres ne figurent qu'au compteur global. Labels : security, container. Titre : Failles image kirexo-prod:latest (N Critical/High) détectées le YYYY-MM-DD (cron) ou Failles image kirexo-prod:<x.y.z> (N Critical/High) détectées le YYYY-MM-DD (release).
Authentification : GITLAB_TOKEN¶
security:container-issue (et security:container-issue:builders ci-dessous) ouvrent l'issue via POST /projects/:id/issues en s'authentifiant avec l'en-tête PRIVATE-TOKEN: ${GITLAB_TOKEN} — pas JOB-TOKEN: ${CI_JOB_TOKEN}. C'est le même PAT que celui consommé par security:composer-audit, tools:version-check et dependencies:renovate ; il est déjà provisionné pour ces jobs et n'introduit donc pas de configuration supplémentaire (cf. Variables CI/CD GitLab).
Pourquoi pas CI_JOB_TOKEN ?
La whitelist de CI_JOB_TOKEN sur GitLab Free couvre Container Registry, Packages, Releases, Job artifacts et quelques autres routes — mais pas l'API REST des issues. Tenter un POST /projects/:id/issues avec JOB-TOKEN: ${CI_JOB_TOKEN} renvoie 401 Unauthorized (testé empiriquement sur le projet, cf. job 14721616686). Le réglage Settings → CI/CD → Token Access → « Allow projects to access this project via CI/CD job tokens » n'y change rien : il étend l'accès inter-projets du job token, pas la whitelist des endpoints. D'où le repli sur le PAT déjà disponible.
Aucun pré-requis Token Access à activer pour ces deux jobs — le PAT est rattaché à un compte, sa portée ne dépend pas du réglage Token Access du projet.
Pourquoi une issue et pas une MR (contrairement à security:composer-audit)
Corriger une CVE d'image revient à bumper le tag de l'image upstream du Dockerfile (ex. FROM dunglas/frankenphp:1.12.7-php8.5-alpine → tag plus récent). C'est précisément le rôle de Renovate, manager dockerfile (cf. renovate.json) : il ouvre la MR de bump dès qu'un tag plus récent est publié. Reproduire ici cette logique (résolution de tag, contraintes semver, maintenance du lockfile) dupliquerait Renovate sans le fiabiliser. L'issue ouverte par security:container-issue reste utile comme signal pré-Renovate : entre l'instant où une CVE est publiée et celui où Renovate la voit, on a déjà une alerte humaine. La même logique s'applique aux jobs builders ci-dessous.
Pourquoi filtrer Critical / High
Une image de prod typique (Debian + extensions PHP + vendor/) accumule plusieurs centaines à plusieurs milliers de CVE Medium / Low / Unknown, soit non corrigeables côté Debian (« won't fix » / « postponed »), soit non exploitables dans le contexte d'usage. Sans filtrage, une issue était créée chaque jour avec ~1000 entrées de bruit, noyant les signaux exploitables. Limiter l'ouverture aux Critical + High garde le signal actionnable ; le récap complet par sévérité reste dans le corps de l'issue pour traçabilité, et l'artifact gl-container-scanning-report.json contient la liste exhaustive pour qui veut creuser.
Jobs container_scanning:builders et security:container-issue:builders (images CI)¶
Mêmes scanner et alerting que ci-dessus, mais ciblés sur les images qui alimentent la chaîne de build CI elle-même : kirexo-base et kirexo-dev. Une CVE critique dans leur OS / libs système (libc, openssl, …) compromettrait tous les jobs PHP et E2E. Cron quotidien uniquement — ces images ne sont pas livrées à l'utilisateur, elles n'ont pas de tag de release à scanner.
Implémentation : extends: container_scanning (réutilise l'image Trivy + le script du template), avec une parallel:matrix sur les deux images.
| Caractéristique | Valeur |
|---|---|
| Stage | maintenance |
parallel.matrix |
CS_BUILDER_IMAGE: [kirexo-base, kirexo-dev] → deux jobs en parallèle. |
CS_IMAGE |
$CI_REGISTRY_IMAGE/$CS_BUILDER_IMAGE:php$PHP_VERSION-alpine — tag effectivement utilisé par les autres jobs CI (et non :latest, qui n'est qu'un alias poussé au tag de release). |
needs: |
docker:build-base et docker:build-dev, tous deux optional: true. Ces deux jobs sont absents du schedule, seul déclencheur du scan : le needs est satisfait par absence. Avant le ticket #270, ils y figuraient en manual jamais joués, et le scan sortait skipped. |
| Déclencheur | $CI_PIPELINE_SOURCE == "schedule" uniquement. |
| Allowed failure | true (hérité de container_scanning). |
| Job d'alerting | security:container-issue:builders — même matrix, lit gl-container-scanning-report.json, n'ouvre une issue que si Critical + High > 0 (même filtrage que security:container-issue). Authentification via PRIVATE-TOKEN: ${GITLAB_TOKEN} (cf. Authentification GITLAB_TOKEN). Titre : Failles image kirexo-base:php8.5-alpine (N Critical/High) détectées le YYYY-MM-DD (ou kirexo-dev:…). Labels security, container. Le corps de l'issue mentionne explicitement que le bump du tag upstream du Dockerfile est porté par Renovate. |
Container Scanning sur tier Free : on parse le rapport nous-mêmes
L'onglet Security et le widget MR sont réservés à GitLab Ultimate. En tier gratuit, les jobs container_scanning et container_scanning:builders produisent bien gl-container-scanning-report.json, mais ce sont security:container-issue et security:container-issue:builders qui le parsent pour décider d'ouvrir une issue — l'alerting est fait par nos soins.
Un seul schedule pour les jobs de cron quotidien
security:composer-audit, dependencies:renovate, tools:version-check, container_scanning, container_scanning:builders et leurs jobs d'alerting partagent le même déclencheur $CI_PIPELINE_SOURCE == "schedule". Une seule schedule quotidienne (ex. 0 5 * * * sur main) suffit à les lancer tous. Voir Configurer l'audit de sécurité quotidien.
Le job pages du stage release utilise lui aussi $CI_PIPELINE_SOURCE == "schedule", mais filtré en plus par $REBUILD_DOCS == "true" : sa schedule hebdo dédiée (cf. Configurer le rebuild hebdomadaire de la doc) ne réveille pas les jobs de cron quotidien, et inversement.
Allowlist container scanning (vulnerability-allowlist.yml)¶
Le fichier vulnerability-allowlist.yml à la racine du repo exclut du rapport les CVE constatées mais assumées, pour qu'elles ne rouvrent pas d'issue via security:container-issue (+ :builders). C'est le mécanisme d'exclusion natif de l'analyseur GitLab Container Scanning (le job n'écrit pas son propre script : il hérite du template Jobs/Container-Scanning.gitlab-ci.yml). Format : la section generalallowlist: liste une CVE par clé, valeur optionnelle = nom de paquet (indicatif). Chaque entrée porte un commentaire de justification obligatoire (paquet + raison de non-exploitabilité ou statut du patch Alpine). Procédure d'ajout/retrait d'une entrée : Configurer l'audit de sécurité quotidien — Résiduel Alpine allowlisté.
Deux points de câblage :
GIT_STRATEGY: fetchest posé dans le blocvariables:du jobcontainer_scanning. Sans checkout du repo, l'analyseur ne trouve pasvulnerability-allowlist.ymlà la racine et l'allowlist est silencieusement ignorée. Le template CS tourne par défaut sans clone complet, d'où ce forçage.- Application aux trois images.
container_scanning:buildersfaitextends: container_scanning: il hérite donc à la fois deGIT_STRATEGY: fetchet de l'allowlist racine (generalallowlist= exclusion globale, toutes images). Une seule entrée couvre donckirexo-prod,kirexo-baseetkirexo-dev.
Aucun seuil bloquant n'est introduit : les jobs restent allow_failure: true. L'allowlist ne fait que taire le résiduel justifié — une CVE Critical/High non allowlistée déclenche toujours l'ouverture d'issue.
Comparatif Debian → Alpine (trace du gain)¶
La migration de l'image de base Debian (dunglas/frankenphp:1-php8.5) vers Alpine (:1-php8.5-alpine) a fait chuter le volume de CVE remonté par Trivy. Chiffres relevés sur les scans réels :
| Périmètre | Debian (dernier tag concerné) | Alpine (:php8.5-alpine) |
|---|---|---|
kirexo-prod — Critical/High |
65, puis 71 un mois plus tard | 0 |
kirexo-prod — total vulnérabilités |
1047 | 0 |
kirexo-base / kirexo-dev — Critical/High |
(mêmes ordres de grandeur, base Debian partagée) | 1 chacune — CVE-2026-33630 sur c-ares 1.34.6-r0 |
Sur kirexo-prod, le apk upgrade --no-cache du stage frankenphp_prod patche le résiduel → 0 vulnérabilité livrée. Le bruit Debian dominant (linux-libc-dev ~22 CVE de headers kernel, famille Perl ~20 CVE) disparaît mécaniquement : ces paquets ne sont pas installés sous Alpine. Le seul résiduel Critical/High est côté builders (non livrés) : CVE-2026-33630 sur c-ares (résolveur DNS transitif), allowlistée en attendant le rebuild des builders sans cache qui récupérera le patch Alpine c-ares 1.34.8-r0.
Pipeline de création de tag¶
Job unique tag:create (stage tag), déclenché par la variable CREATE_TAG=true. Voir le guide Créer un tag de release pour la procédure.
| Caractéristique | Valeur |
|---|---|
| Image | alpine:3 |
| Format du tag | Version sémantique MAJEUR.MINEUR.CORRECTIF sans préfixe v (ex. 0.0.1). Le même nom sert de tag Git, de tag d'image kirexo-prod et de valeur de KIREXO_VERSION. |
| Dernière version | Lue par GET /projects/:id/repository/tags?per_page=100&page=N, paginée jusqu'à une page vide (les anciens tags horodatés et les tags annexes occupent déjà des dizaines d'entrées). Filtre ^[0-9]+\.[0-9]+\.[0-9]+$, puis tri numérique par composante en jq (sort_by(split(".") \| map(tonumber))). Les anciens tags YYYYMMDDHHMM ne passent pas le filtre. |
Nom par défaut (TAG_NAME absent) |
Patch suivante de la dernière version (0.0.3 → 0.0.4) ; 0.0.1 s'il n'existe aucune version semver. |
TAG_NAME imposé — forme |
Semver strict sans zéro de tête : ^(0\|[1-9][0-9]*)\.(0\|[1-9][0-9]*)\.(0\|[1-9][0-9]*)$. Sinon exit 1 : TAG_NAME invalide (…) — version sémantique attendue MAJEUR.MINEUR.CORRECTIF (ex. 0.0.1). |
TAG_NAME imposé — monotonie |
Strictement supérieure à la dernière version, comparée en tableaux d'entiers par jq. S'il n'existe aucune version, seule 0.0.1 est acceptée. Sinon exit 1 : TAG_NAME … n'est pas supérieur à la dernière version …. |
| Méthode | POST /projects/:id/repository/tags via curl --fail |
| Authentification | PRIVATE-TOKEN: $GITLAB_TOKEN |
GIT_STRATEGY |
none (pas besoin de cloner — l'API agit côté serveur) |
| Rule | $CREATE_TAG == "true" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH — borné explicitement à main. Sans cette double condition, déclencher CREATE_TAG=true depuis une feature branch poserait quand même le tag sur main (via ref=$CI_DEFAULT_BRANCH du POST) — surprenant et facile à mal utiliser. |
| Garde-fou pipeline | Avant de créer le tag, interroge GET /projects/:id/pipelines?sha=$CI_COMMIT_SHA&status=success et refuse de taguer si aucune pipeline success n'existe pour le commit ciblé (exit 1). Outrepassable par FORCE_TAG=true. |
| Garde-fou « tag déjà présent » | Avant le POST, interroge GET /projects/:id/repository/tags/$TAG_NAME et capture le code HTTP. 200 → le tag existe déjà (deux déclenchements rapprochés, retry manuel après un succès partiel…) → le job sort en exit 1 avec un message clair (« Le tag … existe déjà — abandon (choisis une version supérieure). ») plutôt que de laisser le POST échouer en 409 cryptique. 404 → tag libre, on continue. Tout autre code (5xx, token expiré…) → abandon : on ne tente pas aveuglément un POST. |
| Effet de bord | GitLab détecte le tag créé et démarre automatiquement la pipeline $CI_COMMIT_TAG (quality + test + docker + release). |
Garde-fou : pipeline verte exigée¶
Comme cette pipeline tourne sur main, $CI_COMMIT_SHA correspond au dernier commit de main. Avant de créer le tag, tag:create exige qu'au moins une pipeline success existe pour ce SHA (typiquement la pipeline de validation jouée au merge). Le but : ne jamais figer une release sur un commit dont la CI est rouge ou encore en cours.
Le contrôle est fail-safe : si l'appel API échoue (token invalide, réseau), le compteur de pipelines réussies retombe à 0 et le job bloque — il refuse de taguer plutôt que de risquer une release non validée.
| Variable | Valeur | Effet sur le garde-fou |
|---|---|---|
| (absente) | — | Garde-fou actif : pas de tag sans pipeline verte sur le commit. |
FORCE_TAG |
true |
Garde-fou ignoré — le tag est créé sans vérifier le statut de pipeline. Réservé aux cas exceptionnels. |
FORCE_TAG se passe en plus de CREATE_TAG=true, au déclenchement de la pipeline (UI ou glab, cf. Créer un tag de release). Elle n'a aucun effet hors de la pipeline CREATE_TAG=true.
Format de version : semver depuis 0.0.1¶
Les releases suivent le Versionnement Sémantique, première version 0.0.1. La version de référence est le tag Git seul, sans fichier VERSION. Les tags horodatés YYYYMMDDHHMM des releases antérieures restent dans le dépôt comme historique, mais ne sont jamais considérés comme des versions : ils ne déclenchent aucune pipeline, ne sont ni triés ni comparés, et ne sont candidats ni à :latest ni au rebuild de la doc. Seule exception : le dernier d'entre eux sert de borne basse aux notes de la toute première release semver (cf. Job release:create).
Pourquoi semver plutôt qu'un horodatage :
- le nom porte l'ampleur du changement : un installateur qui lit
KIREXO_VERSION=0.0.2sait qu'il s'agit d'une correction compatible de0.0.1, là où un horodatage ne dit rien des ruptures. Tant que la version est en0.y.z, une montée de mineure signale une rupture pour l'installateur (variable renommée, étape manuelle, migration non réversible) ; la majeure est réservée à1.0.0; - le choix du niveau est une décision explicite, prise au moment de la release (
castor tag:next-version --bump=…, skill/creer-tag), au lieu d'être dérivé de l'heure de la pose.
Le tri n'est jamais lexical
En comparaison de chaînes, "0.10.0" < "0.9.0" et "0.0.10" < "0.0.9". Partout où une dernière version est calculée, la comparaison porte sur les trois composantes numériques :
| Contexte | Méthode |
|---|---|
| PHP (Castor) | SemanticVersion::compareTo() (castor/src/Release/SemanticVersion.php) |
jq (job tag:create) |
sort_by(split(".") \| map(tonumber)), comparaison de tableaux d'entiers |
Shell POSIX (pages, release:create, prepare.sh) |
grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' \| sort -t. -k1,1n -k2,2n -k3,3n — sort -V n'est pas garanti sous BusyBox |
Sur un ensemble déjà filtré par ^[0-9]+\.[0-9]+\.[0-9]+$, le tri par clés numériques est équivalent à sort -V.
Release et déploiement de la documentation¶
Sept jobs dans .gitlab/ci/release.yml. pages (déploiement de la doc) tourne sur tag de release et sur la schedule hebdo de rebuild (REBUILD_DOCS=true). Les six autres tournent exclusivement sur tag de release et forment une chaîne de needs, dans laquelle s'intercalent, en parallèle, les jobs docker:test-install et docker:test-install-traefik — déclarés dans .gitlab/ci/docker.yml, mais placés dans le stage release :
┌─> docker:test-install ──────────┐ ┌─> release:links-arm64
release:sbom → release:bundle-render┤ ├─> release:bundle-publish → release:create┤
└─> docker:test-install-traefik ──┘ └─> release:site-deploy
| Job | needs: |
|---|---|
release:sbom |
docker:manifest-prod (dotenv des digests et de KIREXO_PROD_ARM64_BUILT), docker:build-supply-chain |
release:bundle-render |
docker:manifest-prod (artifacts: true, pour KIREXO_PROD_ARM64_BUILT), release:sbom |
docker:test-install |
docker:manifest-prod (dotenv des digests), release:bundle-render (artifact release-assets/) |
docker:test-install-traefik |
docker:manifest-prod (artifacts: false), release:bundle-render (artifact release-assets/) |
release:bundle-publish |
release:bundle-render, docker:manifest-prod (artifacts: true, pour KIREXO_PROD_ARM64_BUILT), docker:test-install, docker:test-install-traefik, docker:sign-prod |
release:create |
release:bundle-publish, docker:manifest-prod (artifacts: true, pour KIREXO_PROD_ARM64_BUILT), docker:sign-prod |
release:links-arm64 |
release:create, docker:manifest-prod (artifacts: true, pour KIREXO_PROD_ARM64_BUILT) |
release:site-deploy |
docker:build-dev, release:create |
release:site-deploy n'attend pas release:links-arm64.
Les fichiers publiés, leurs permaliens et le script infra/release/publish-bundle.sh sont décrits dans Assets de release et permaliens.
Job pages¶
Le job s'appelle obligatoirement pages pour que GitLab Pages collecte l'artifact public/ en tant que site déployé — c'est une convention GitLab non négociable.
| Caractéristique | Valeur |
|---|---|
| Image | $KIREXO_DOCS_IMAGE (kirexo-docs:latest, pré-buildée par docker:build-docs à partir de mkdocs/Dockerfile). entrypoint: [""] neutralise l'entrypoint mkdocs hérité pour que GitLab CI lance le script via le shell. |
| Commande | mkdocs build --strict -d public (préfixée, sur schedule uniquement, d'un git checkout --detach <dernière version semver>). |
| Mode strict | Activé — un lien cassé, un snippet manquant ou un avertissement de plugin échoue le build. |
GIT_DEPTH |
0 (histoire git complète, requise par git-revision-date-localized et par le git checkout <tag> du déclencheur schedule). |
| Pre-script | Aucun. mkdocs-material et les plugins (imaging, git-revision-date) sont déjà installés dans l'image kirexo-docs — plus de apk add ni de pip install à chaque déploiement. |
| Artifact | public/ (collecté automatiquement par GitLab Pages). |
artifacts:expire_in |
1 week — GitLab Pages conserve nativement le contenu du dernier pages réussi même après expiration de l'artifact ; la fenêtre courte évite simplement d'accumuler des artifacts obsolètes (un par tag + un par rebuild hebdo). Si la doc devait disparaître plus de 7 jours sans nouveau tag ni nouveau cron, la schedule weekly écrit de toute façon une nouvelle version avant. |
| Déclencheurs | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ (tag de release) ou $CI_PIPELINE_SOURCE == "schedule" && $REBUILD_DOCS == "true" (schedule hebdo de rebuild — cf. ci-dessous). |
L'image kirexo-docs étant construite à partir du même mkdocs/Dockerfile que l'environnement local, le rendu de la doc en CI est à parité exacte avec un build local. Sur tag, docker:build-docs (stage docker) tourne avant pages (stage release) : l'image :latest est toujours fraîche au moment du déploiement.
Rebuild hebdomadaire (REBUILD_DOCS=true)¶
Une schedule GitLab dédiée (variable REBUILD_DOCS=true) déclenche pages une fois par semaine pour reconstruire la doc figée sur la dernière version semver, sans attendre la prochaine release. Objectif : profiter d'une éventuelle mise à jour de l'image kirexo-docs — patch de mkdocs-material, bump de plugin (typiquement par Renovate sur l'image kirexo-docs) — entre deux releases. Le contenu publié reste celui de la version effectivement en production.
Mécanique du job sur ce déclencheur :
git tag --list | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -t. -k1,1n -k2,2n -k3,3n | tail -1récupère la plus haute version semver (tri numérique par composante, cf. Le tri n'est jamais lexical). Les anciens tags horodatésYYYYMMDDHHMMet les tags annexes sont ignorés.- Si aucune version semver n'existe, le job affiche
Aucun tag de version semver dans le repo — rien à régénérer.et sort en0; GitLab Pages conserve alors le dernier déploiement. - Sinon,
git checkout --detach $LAST_TAGrepositionne HEAD sur ce commit (HEAD détaché — aucune branche à toucher). mkdocs build --strict -d publicproduit le site, collecté ensuite par GitLab Pages comme un déploiement normal.
La configuration de cette schedule est documentée dans Configurer le rebuild hebdomadaire de la doc.
L'URL canonique cible est https://doc.kirexo.app/ — voir le guide Configurer le domaine GitLab Pages pour la configuration DNS et le certificat Let's Encrypt.
Job release:sbom¶
Génère sur chaque tag de release deux ou quatre Software Bill of Materials de l'image kirexo-prod:$CI_COMMIT_TAG : pour chaque architecture présente dans l'index (linux/amd64 toujours, linux/arm64 si KIREXO_PROD_ARM64_BUILT=true), un inventaire exhaustif des paquets et libs embarqués (OS Alpine + extensions PHP + dépendances Composer présentes dans vendor/), en deux formats. Les deux formats coexistent car les écosystèmes consommateurs ne lisent pas le même :
- SPDX JSON (Linux Foundation, format ISO 5962) — référence côté audit / juristes / conformité (OpenChain, NTIA Minimum Elements).
- CycloneDX JSON (OWASP) — référence côté outillage de sécurité (Dependency-Track, Snyk, Trivy en mode SBOM, GitHub Advanced Security).
| Caractéristique | Valeur |
|---|---|
| Stage | release |
| Image | $KIREXO_SUPPLY_CHAIN_IMAGE (image custom Alpine + cosign + syft, cf. Image supply chain). Pas d'override d'entrypoint nécessaire — l'image embarque déjà sh. |
needs: |
docker:manifest-prod avec artifacts: true (son dotenv manifest-prod.env fournit KIREXO_PROD_AMD64_DIGEST, KIREXO_PROD_ARM64_BUILT et, si arm64 est présent, KIREXO_PROD_ARM64_DIGEST ; l'image elle-même est scannée via le registry, pas via une tarball locale) et docker:build-supply-chain avec artifacts: false (sans cette image, le job n'a pas de binaire syft). |
| Scan | Pour amd64, puis arm64 seulement si KIREXO_PROD_ARM64_BUILT=true : syft "registry:$repo@$digest", où $repo vaut $CI_REGISTRY_IMAGE/kirexo-prod et $digest le digest de l'image de plateforme lu dans le dotenv. Scan registry distant, pas de docker pull local. Un digest absent pour une architecture retenue fait échouer le job (Digest <arch> absent de manifest-prod.env.) : amd64 est exigé sans condition. Sans arm64, la trace affiche Index linux/amd64 seul (KIREXO_PROD_ARM64_BUILT≠true) : SBOM amd64 seuls. |
| Scan par digest | Le SBOM décrit exactement l'image de plateforme signée par docker:sign-prod, sans dépendre de la plateforme que syft choisirait s'il recevait l'index. |
| Authentification registry | SYFT_REGISTRY_AUTH_AUTHORITY / SYFT_REGISTRY_AUTH_USERNAME / SYFT_REGISTRY_AUTH_PASSWORD câblés sur les variables CI_REGISTRY* natives — pas de nouvelle variable à provisionner. |
| Artifacts produits | Deux ou quatre fichiers, capturés par le motif sbom-kirexo-prod-*.json : sbom-kirexo-prod-$CI_COMMIT_TAG-linux-amd64.spdx.json et sbom-kirexo-prod-$CI_COMMIT_TAG-linux-amd64.cdx.json toujours ; sbom-kirexo-prod-$CI_COMMIT_TAG-linux-arm64.spdx.json et sbom-kirexo-prod-$CI_COMMIT_TAG-linux-arm64.cdx.json si arm64 est présent. |
artifacts.expire_in |
1 year. L'artifact n'est plus lié à la release : il ne sert qu'à passer les fichiers à release:bundle-render, qui les republie dans le Generic Package Registry, sans expiration. |
| Déclencheur | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ uniquement. |
interruptible |
false. |
Job release:bundle-render¶
Rend le bundle d'installation et rassemble les SBOM dans un artifact, sans rien publier.
| Caractéristique | Valeur |
|---|---|
| Stage | release |
| Image | alpine:3.24 |
needs: |
docker:manifest-prod avec artifacts: true (l'image du tag doit exister avant qu'un .env.example ne la cite, et l'index public :$CI_COMMIT_TAG n'existe qu'après le manifeste ; le dotenv fournit KIREXO_PROD_ARM64_BUILT) et release:sbom avec artifacts: true (récupère les SBOM). |
| Script | sh infra/release/publish-bundle.sh render "$CI_COMMIT_TAG" release-assets, puis cp de sbom-kirexo-prod-$CI_COMMIT_TAG-linux-amd64.spdx.json et sbom-kirexo-prod-$CI_COMMIT_TAG-linux-amd64.cdx.json dans release-assets/ (toujours), puis, seulement si KIREXO_PROD_ARM64_BUILT=true, cp de sbom-kirexo-prod-$CI_COMMIT_TAG-linux-arm64.spdx.json et sbom-kirexo-prod-$CI_COMMIT_TAG-linux-arm64.cdx.json. Sans arm64, la trace affiche Index linux/amd64 seul (KIREXO_PROD_ARM64_BUILT≠true) : aucun SBOM arm64 copié. Noms explicites, sans motif générique : un SBOM manquant fait échouer le cp. |
| Artifact | release-assets/ — compose.yaml et README.md copiés depuis install/, .env.example avec KIREXO_VERSION=$CI_COMMIT_TAG, les deux ou quatre SBOM. expire_in: 1 week. |
| Déclencheur | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ uniquement. |
interruptible |
false. |
| Effet en cas d'échec | Source manquante, compose.yaml sans ${KIREXO_VERSION, zéro ou plusieurs lignes KIREXO_VERSION=, SBOM manquant : le job échoue, rien n'est publié, aucune release n'est créée. |
La substitution de KIREXO_VERSION est faite par la pipeline, jamais à la main : cf. Substitution de KIREXO_VERSION.
Job docker:test-install¶
Joue le bundle rendu par release:bundle-render comme un tiers : fichiers de release-assets/ utilisés tels quels, images tirées du registry sans authentification, aucun Castor dans la stack. Le détail de la stack, des étapes S0 à S17 et des codes de sortie est dans castor docker:test-install, qui rejoue le même script en local.
| Caractéristique | Valeur |
|---|---|
| Fichier | .gitlab/ci/docker.yml, en fin de fichier. |
| Stage | release — et non docker : le job consomme l'artifact de release:bundle-render, qui vit dans ce stage, et un needs ne peut viser qu'un job d'un stage antérieur ou identique. |
| Template | extends: .docker_job (docker:29 + service docker:29-dind). |
before_script |
docker version seul. Il remplace celui de .docker_job : aucun docker login — le pull anonyme fait partie de ce qui est testé. |
needs: |
docker:manifest-prod avec artifacts: true (dotenv manifest-prod.env, pour KIREXO_PROD_INDEX_DIGEST) et release:bundle-render avec artifacts: true (release-assets/ : compose.yaml et .env.example rendus). |
| Script | sh infra/image/install-e2e.sh --bundle-dir "$CI_PROJECT_DIR/release-assets" --version "$CI_COMMIT_TAG" --expected-digest "$KIREXO_PROD_INDEX_DIGEST" --pull, précédé d'un contrôle : "${KIREXO_PROD_INDEX_DIGEST:?…}" qui fait échouer le job si le dotenv n'a pas été publié. |
| Outils | Aucun apk add : les requêtes HTTP partent de l'intérieur du conteneur php de la stack testée, l'image docker:29 n'a besoin ni de curl ni de jq. |
| Artifacts | var/install-e2e/, when: always, expire_in: 1 month. Exclus : var/install-e2e/.env et var/install-e2e/.env.* — secrets du run, jamais publiés, même jetables. |
timeout |
30 minutes. |
| Déclencheur | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ uniquement : ni MR, ni main, ni schedule. |
interruptible |
false. |
| Consommateur | release:bundle-publish, par needs (artifacts: false). |
Digest tiré. À l'étape S4, le script compare le digest que Docker associe à l'image tirée à KIREXO_PROD_INDEX_DIGEST : la version publiée tire l'index construit par cette même pipeline, et pas une autre image.
amd64 seulement. Le job tourne sur le runner du mainteneur (amd64, tag kirexo-self hérité de default, cf. Runners), qui tire la variante amd64 de l'index ; le contrôle de digest, lui, porte sur l'index. Doubler ce test DinD sur le runner arm64 (2 vCPU) coûterait trop cher : arm64, quand il est publié, reste couvert par le garde-fou et le smoke test HTTP, joués nativement dans docker:build-prod-arm64 (cf. Script partagé par les deux jambes).
Effet en cas d'échec. Au premier contrôle en échec, la trace affiche les logs de tous les services de la stack, puis la stack est démontée. release:bundle-publish ne tourne pas : rien n'est publié dans le Generic Package Registry et release:create ne crée aucune release. L'artifact var/install-e2e/ (logs, résultats, empreinte si l'étape S16 a été atteinte) reste consultable depuis le job.
Empreinte. Sur succès, var/install-e2e/footprint.md porte l'empreinte mesurée de la stack pour la version du tag ; c'est la valeur à reporter dans install/README.md — cf. Reporter l'empreinte dans install/README.md.
Quota Docker Hub
Les images tierces de la stack (PostgreSQL, Redis, RabbitMQ, Mailpit) sont tirées anonymement de Docker Hub, soumises au quota par IP du runner, comme dans les autres jobs DinD. Un pull en échec sort en 2 avec la sortie de docker compose pull, sans être confondu avec un défaut du bundle.
Job docker:test-install-mr¶
Même scénario que docker:test-install, joué en MR sur une image prod construite dans le job : hors tag, aucune image installable n'existe dans le registry. C'est l'équivalent CI de castor docker:test-install joué sur l'image construite localement, côté hôte.
| Caractéristique | Valeur |
|---|---|
| Fichier | .gitlab/ci/docker.yml, juste après docker:test-install. |
| Stage | docker (hérité de .docker_job). |
| Template | extends: .docker_job (docker:29 + service docker:29-dind, docker login au registry pour le cache). |
needs: |
[] — démarre dès le début de la pipeline. |
| Script | 1. docker build --pull --cache-from $KIREXO_PROD_IMAGE --target frankenphp_prod --tag kirexo-prod:check-local . ; 2. sh infra/release/publish-bundle.sh render 0.0.0 "$CI_PROJECT_DIR/var/install-e2e-bundle" (bundle rendu en version sentinelle 0.0.0) ; 3. lecture du nom d'image kirexo-prod:… attendu par le bundle rendu (docker compose … config --images, valeurs factices pour les variables :?), puis docker tag kirexo-prod:check-local sous ce nom ; 4. sh infra/image/install-e2e.sh --bundle-dir "$CI_PROJECT_DIR/var/install-e2e-bundle" --version 0.0.0, sans --pull ni --expected-digest. |
| Artifacts | var/install-e2e/, when: always, expire_in: 1 week. Exclus : var/install-e2e/.env et var/install-e2e/.env.*. |
timeout |
45 minutes (build de l'image compris). |
| Déclencheur | MR ($CI_PIPELINE_SOURCE == "merge_request_event") qui modifie install/compose.yaml ou install/.env.example, Renovate compris. Absent sur main, en schedule et sur tag. |
| Bloquant | Oui : ni when: manual, ni allow_failure. Un bundle qui ne démarre pas ne fusionne pas. |
interruptible |
true. |
Pourquoi un job distinct. docker:test-install reste réservé au tag : il teste l'image publiée, par digest et en pull anonyme, ce qui n'a de sens que dans la pipeline qui la publie. Le job de MR teste le bundle contre l'image du commit. Il a été ajouté après une montée postgres:18-alpine du bundle, automergée par Renovate sans qu'aucun test ne la joue, et qui rendait une installation neuve non démarrable.
Job docker:test-install-traefik¶
Joue le bundle rendu par release:bundle-render comme un tiers qui a déjà un Traefik : le .env reçoit exactement les lignes de la section Traefik de Installer Kirexo derrière un reverse proxy, et la stack démarre derrière un vrai Traefik. C'est la seule configuration de reverse proxy testée : Caddy, Nginx, Apache et Nginx Proxy Manager sont publiés comme configurations de référence, non testées. Le détail du script est dans castor docker:test-install, qui le rejoue en local avec --edge=traefik.
| Caractéristique | Valeur |
|---|---|
| Fichier | .gitlab/ci/docker.yml, juste après docker:test-install. |
| Stage | release, pour la même raison que docker:test-install : il consomme l'artifact de release:bundle-render. |
| Template | extends: .docker_job (docker:29 + service docker:29-dind). |
before_script |
docker version seul : aucun docker login, le pull anonyme fait partie de ce qui est testé. |
needs: |
docker:manifest-prod avec artifacts: false (aucun contrôle de digest ici) et release:bundle-render avec artifacts: true (release-assets/). |
| Script | sh infra/image/install-e2e-traefik.sh --bundle-dir "$CI_PROJECT_DIR/release-assets" --version "$CI_COMMIT_TAG" --pull. |
| Surcharge Compose | infra/image/install-e2e-traefik.compose.yaml : un service traefik (image traefik:v3.7.13@sha256:24841fe2de7304c149343d877d2923b4c8800a38ba015dea9174c23b20e344a0), fournisseur Docker (exposedbydefault=false), points d'entrée web (:80) et websecure (:443), résolveur nommé letsencrypt dont l'autorité de certification est volontairement injoignable, socket Docker monté en lecture seule, aucun port publié. |
| Artifacts | var/install-e2e-traefik/, when: always, expire_in: 1 month. Exclus : var/install-e2e-traefik/.env et var/install-e2e-traefik/.env.*. |
timeout |
30 minutes. |
| Déclencheur | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ uniquement. |
interruptible |
false. |
| Consommateur | release:bundle-publish, par needs (artifacts: false) : une configuration Traefik cassée bloque la release. |
Contrôles, dans l'ordre d'exécution. Les requêtes partent du conteneur php, branché sur le réseau de Traefik, avec curl --connect-to ::traefik:443 -k : tout nom d'hôte est envoyé à Traefik, qui sert son certificat par défaut, auto-signé.
| # | Contrôle | Requête | Attendu |
|---|---|---|---|
| T1 | Routage | GET https://app.kirexo.test/admin/login |
200 et le formulaire de connexion (jeton CSRF présent), relancé jusqu'à 120 s le temps que Traefik découvre le routeur. |
| T3 | Connexion | Premier administrateur créé par app:user:create … --role=both, puis POST /admin/login_check avec Origin: https://app.kirexo.test |
Redirection de connexion réussie. |
| T2 | HTTPS reconnu | En-têtes de la réponse de T3 | Un Set-Cookie porte l'attribut Secure : Kirexo a cru le X-Forwarded-Proto de Traefik (TRUSTED_PROXIES). |
| T4 | Flux temps réel | curl -N --max-time 5 sur /.well-known/mercure?topic=install-e2e (abonnement anonyme) |
Statut 200 et Content-Type: text/event-stream reçus avant la coupure volontaire de curl. |
| T5 | Domaines de site | GET https://blog.exemple.test/ (dans la règle), puis GET https://inconnu.exemple.test/ (hors règle) |
Le premier atteint Kirexo ; le second reçoit la réponse 404 page not found de Traefik. |
Chaque verdict est une fonction pure de infra/image/install-e2e.lib.sh (install_e2e_traefik_routing_verdict, install_e2e_traefik_secure_verdict, install_e2e_traefik_sse_verdict, install_e2e_traefik_host_verdict) ; T3 réutilise smoke_login_verdict.
Ce que le test ne couvre pas. L'émission d'un certificat par le résolveur (aucun accès à Let's Encrypt en CI), et l'alias réseau kirexo du service php, que Traefik n'utilise pas (il joint le conteneur par son adresse sur le réseau du label traefik.docker.network).
Image Traefik épinglée par tag et digest
La surcharge tire Traefik 3.7.13, épinglé par tag et digest relevés lors d'un essai réel du test. Version minimale : 3.6.1, les précédentes échouant sur le fournisseur Docker face à Docker Engine 29 (API minimale 1.44), le démon du job CI. La trace du test affiche l'image effectivement utilisée, relevée par docker compose config --images.
Effet en cas d'échec. Arrêt au premier contrôle en échec ; la trace affiche les logs de tous les services, Traefik compris, puis la stack et le réseau de test sont supprimés. release:bundle-publish ne tourne pas : rien n'est publié.
Job release:bundle-publish¶
Envoie release-assets/ dans le Generic Package Registry du projet (paquet kirexo, version $CI_COMMIT_TAG). Registry de paquets plutôt qu'artifacts : un artifact expire, et un permalien latest vers un fichier d'installation ne doit jamais finir en 404.
| Caractéristique | Valeur |
|---|---|
| Stage | release |
| Image | alpine:3.24, curl installé en before_script (apk add --no-cache curl). |
needs: |
release:bundle-render avec artifacts: true, docker:manifest-prod avec artifacts: true (son dotenv fournit KIREXO_PROD_ARM64_BUILT, qui décide si release_bundle_assets exige les deux SBOM arm64), docker:test-install et docker:test-install-traefik avec artifacts: false — le bundle n'est publié que s'il s'est installé, a passé tous les contrôles du test d'installation et fonctionne derrière Traefik — et docker:sign-prod avec artifacts: false : le paquet, lisible sans jeton, n'est publié qu'une fois l'image citée par le .env.example signée et vérifiée. |
| Script | sh infra/release/publish-bundle.sh upload "$CI_COMMIT_TAG" release-assets — envoie les fichiers de release_bundle_assets : cinq sans arm64, sept avec. Le script hérite de KIREXO_PROD_ARM64_BUILT par l'environnement du job (cf. Cinq ou sept assets). |
| Authentification | CI_JOB_TOKEN, en-tête JOB-TOKEN — pas de GITLAB_TOKEN. |
| Déclencheur | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ uniquement. |
interruptible |
false. |
| Effet en cas d'échec | Fichier manquant : aucun envoi. Envoi en échec : arrêt au premier fichier fautif. Dans les deux cas, release:create ne tourne pas. |
Rendu et publication sont deux jobs distincts pour qu'un contrôle portant sur l'artifact rendu s'intercale avant l'envoi : c'est la place de docker:test-install. Une relance du job ajoute des doublons au paquet, sans changer les URL (cf. upload).
Job release:create¶
| Caractéristique | Valeur |
|---|---|
| Image | registry.gitlab.com/gitlab-org/release-cli:v0.24.0 (version épinglée — pas de :latest ; Renovate suit ce tag). |
| Authentification | CI_JOB_TOKEN (automatique — pas besoin de GITLAB_TOKEN). |
needs: |
release:bundle-publish avec artifacts: false, docker:manifest-prod avec artifacts: true (seul son dotenv est lu, pour KIREXO_PROD_ARM64_BUILT) et docker:sign-prod avec artifacts: false, en dernier. release:bundle-publish dépend de release:bundle-render, qui dépend de release:sbom : l'attendre suffit pour que les fichiers existent dans le paquet au moment où la release les référence. docker:sign-prod empêche de publier une release dont l'image n'est pas signée — avec needs, l'ordre des stages ne suffirait pas à bloquer le job. Si l'un des deux échoue, release:create ne tourne pas et la release GitLab n'est pas créée. |
GIT_DEPTH |
0 (histoire complète, requise par git tag --list --merged HEAD^ pour trouver la borne basse et par git log). |
| Borne basse | Plus haute version semver atteignable depuis HEAD^ (grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' puis sort -t. -k1,1n -k2,2n -k3,3n). À défaut — première release semver uniquement —, le dernier ancien tag horodaté ^[0-9]{12}$ atteignable depuis HEAD^ par date de création, pour ne pas recopier l'historique déjà publié. Les tags annexes (etape4-*…) ne sont jamais retenus. |
| Description | Changelog généré à la volée — ## Changements depuis <borne> puis git log <borne>..<tag> au format * %s (%h). Sans aucune borne, ## Première release et tous les commits depuis la racine. Si KIREXO_PROD_ARM64_BUILT ne vaut pas true, une section ## Architecture est ajoutée en fin de note (cf. ci-dessous). |
release.tag_name |
$CI_COMMIT_TAG |
release.name |
Release $CI_COMMIT_TAG |
release.assets.links |
Cinq entrées pointant sur le paquet générique : $CI_API_V4_URL/projects/$CI_PROJECT_ID/packages/generic/kirexo/$CI_COMMIT_TAG/<fichier>. Trois fichiers d'installation en link_type: package (/compose.yaml, /.env.example, /README.md), deux SBOM linux/amd64 en link_type: other (/sbom/kirexo-prod-linux-amd64.spdx.json, /sbom/kirexo-prod-linux-amd64.cdx.json). Chaque entrée déclare un direct_asset_path sans version, qui donne les permaliens stables …/-/releases/permalink/latest/downloads/<chemin> et …/-/releases/<tag>/downloads/<chemin>. Les deux liens SBOM linux/arm64 sont posés par release:links-arm64. |
Le bloc release n'utilise que des variables prédéfinies : une variable posée dans script n'est pas disponible pour son expansion, et aucun lien ne peut y être conditionnel. La clé filepath, dépréciée, n'est pas utilisée. Tableau complet des liens, permaliens et sémantique de latest : Assets de release et permaliens.
Section « Architecture ». Quand KIREXO_PROD_ARM64_BUILT ne vaut pas exactement true, le script ajoute à RELEASE_NOTES.md :
## Architecture
Cette version est publiée pour linux/amd64 uniquement : l'image arm64 n'a pas pu être construite.
castor ci:local et direct_asset_path
Le schéma JSON embarqué par gitlab-ci-local ne connaît que filepath pour les liens de release et rejetterait direct_asset_path. castor ci:local ignore ce seul chemin du schéma ; le reste de la validation est inchangé.
Les cinq liens sont visibles dans le bloc « Assets » de la release GitLab dès qu'elle est publiée, puis sept une fois release:links-arm64 passé si arm64 est publié (cf. SBOM disponible en asset de la release).
Job release:links-arm64¶
Ajoute à la release les deux liens SBOM linux/arm64, seulement si l'image arm64 a été publiée. Le bloc release.assets.links de release:create est statique : il ne peut pas rendre un lien conditionnel, d'où ce job distinct qui passe par l'API Release Links.
| Caractéristique | Valeur |
|---|---|
| Fichier | .gitlab/ci/release.yml, juste après release:create. |
| Stage | release |
| Image | alpine:3.24, curl installé en before_script (apk add --no-cache curl). |
| Runner | Aucun tags : hérite de default: tags: [kirexo-self] (cf. Runners). |
needs: |
release:create avec artifacts: false (la release doit exister) et docker:manifest-prod avec artifacts: true (dotenv, pour KIREXO_PROD_ARM64_BUILT). |
| Condition | Si KIREXO_PROD_ARM64_BUILT ne vaut pas true : affiche Release linux/amd64 seule (KIREXO_PROD_ARM64_BUILT≠true) : aucun lien SBOM arm64 à poser. et sort en 0. |
| Appel | POST $CI_API_V4_URL/projects/$CI_PROJECT_ID/releases/$CI_COMMIT_TAG/assets/links, un par lien, curl --fail-with-body --silent --show-error --retry 3, champs name, url, direct_asset_path, link_type=other. |
| Authentification | CI_JOB_TOKEN, en-tête JOB-TOKEN. Le jeton n'est jamais affiché (ni set -x, ni écho de l'en-tête). |
| Déclencheur | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ uniquement. |
interruptible |
false. |
Liens posés, identiques à ceux que portait release:create avant que arm64 ne devienne best-effort :
name |
Fichier du paquet (url) |
direct_asset_path |
|---|---|---|
SBOM linux/arm64 (SPDX JSON) |
sbom-kirexo-prod-$CI_COMMIT_TAG-linux-arm64.spdx.json |
/sbom/kirexo-prod-linux-arm64.spdx.json |
SBOM linux/arm64 (CycloneDX JSON) |
sbom-kirexo-prod-$CI_COMMIT_TAG-linux-arm64.cdx.json |
/sbom/kirexo-prod-linux-arm64.cdx.json |
Sortie par lien : ✓ lien posé : <nom>, ou ✓ lien déjà présent : <nom> si l'API répond que le lien existe déjà (has already been taken, nom et URL étant uniques dans une release). Le job est donc rejouable. Toute autre réponse affiche ✗ <nom> suivi du corps de la réponse, et fait échouer le job.
Message d'unicité à confirmer
Le texte de l'erreur d'unicité de l'API Release Links n'est pas documenté par GitLab ; has already been taken est le message de validation attendu. S'il diffère, un rejeu échoue au lieu de compter le lien comme présent : aucun lien erroné n'est publié.
release:site-deploy n'attend pas ce job.
Job release:site-deploy¶
Construit, vérifie puis publie le site vitrine www.kirexo.app à la version du tag. Le fournisseur (deploybase ou OVH), les contrôles et les codes de sortie sont décrits dans castor site:deploy ; la configuration manuelle dans Publier le site vitrine.
| Caractéristique | Valeur |
|---|---|
| Fichier | .gitlab/ci/release.yml, en fin de fichier. |
| Stage | release |
| Image | $KIREXO_DEV_IMAGE (lftp pour le repli OVH, Chromium et Node pour site:check). |
needs: |
docker:build-dev avec artifacts: false (image du tag fraîchement reconstruite) et release:create avec artifacts: false : le site n'annonce une version qu'une fois sa release GitLab publiée, donc une pipeline de tag rouge ne publie rien. |
| Variables | npm_config_cache et CHROMEDRIVER_SKIP_DOWNLOAD, comme quality:site-check. |
| Cache | Clé site-npm sur package.json, chemin .npm/, policy: pull. |
resource_group |
site-vitrine : deux tags rapprochés ne déploient jamais en parallèle. |
environment |
site-vitrine, URL https://www.kirexo.app/. |
| Script | castor site:build, castor site:check, castor site:deploy --expect-version="$CI_COMMIT_TAG". |
| Secrets | DEPLOYBASE_API_KEY, DEPLOYBASE_PROJECT_ID (ou OVH_FTP_*), Protected : disponibles seulement sur les tags protégés (motif *.*.*). Cf. Variables CI/CD GitLab. |
| Déclencheur | $CI_COMMIT_TAG =~ /^[0-9]+\.[0-9]+\.[0-9]+$/ uniquement. |
interruptible |
false : un déploiement interrompu à mi-envoi laisserait une session ouverte et le domaine sur l'ancienne version. |
| Effet en cas d'échec | La release GitLab est déjà créée et n'est pas annulée. Un échec avant tout envoi (contrôles locaux, sortie 2) laisse le site sur la version précédente. Corriger la cause puis relancer le job (Retry). |
Revenir à une version précédente revient à relancer ce job sur la pipeline du tag précédent : cf. Publier le site vitrine › Revenir à une version précédente.
Templates PHP réutilisables¶
Définis dans .gitlab-ci.yml, hérités par les jobs quality:* et test:*.
| Template | Image | Services | Particularité |
|---|---|---|---|
.php_quality_job |
KIREXO_BASE_IMAGE |
aucun | Léger. Style, lint statique, vérifs sans Postgres. Cache vendor/ en policy: pull (lecture seule) — le remplissage est délégué à build:vendor, seul job en pull-push (cf. Cache Composer). |
.php_service_job |
KIREXO_BASE_IMAGE |
postgres:18-alpine, redis:8-alpine, typesense/typesense:0.25.2 |
Étend .php_quality_job. Injecte les DSN applicatifs (DATABASE_URL avec serverVersion=18, REDIS_URL, MESSENGER_TRANSPORT_DSN: sync://, etc.). |
.php_phpstan_job |
KIREXO_BASE_IMAGE |
(idem .php_service_job) |
APP_ENV=dev + cache:warmup. Le containerXmlPath de phpstan.dist.neon pointe sur var/cache/dev/. |
.php_test_job |
KIREXO_BASE_IMAGE |
(idem .php_service_job) |
Force POSTGRES_DB: app_test côté service Postgres pour matcher le suffixe _test ajouté par when@test dans config/packages/doctrine.yaml. before_script limité à composer install — la migration et le chargement des fixtures sont délégués à tests/bootstrap.php (cf. Préparation BDD côté tests). |
.php_e2e_job |
KIREXO_DEV_IMAGE |
(idem .php_service_job) |
Étend .php_test_job (donc hérite aussi de la prise en charge automatique de la BDD par le bootstrap). Bascule sur l'image dev (Chromium + chromedriver). PANTHER_* configurés pour le mode headless CI. |
Le MESSENGER_TRANSPORT_DSN: sync:// côté CI court-circuite RabbitMQ : les messages sont traités en process. C'est volontaire — la CI vérifie la logique métier, pas le transport AMQP.
Pourquoi pas de migrations:migrate ni fixtures:load dans before_script
Avant centralisation côté tests/bootstrap.php, le before_script du .php_test_job jouait explicitement les migrations puis les fixtures. La logique a été déplacée dans le bootstrap PHPUnit pour qu'un développeur local ait exactement la même séquence de préparation qu'en CI, sans avoir à recopier des étapes dans un script. Le service Postgres CI a juste besoin de la variable POSTGRES_DB: app_test pour que la base existe au bon nom dès le démarrage du conteneur.
Authentification Composer auprès de GitHub¶
Le before_script de .php_quality_job (.gitlab-ci.yml) authentifie Composer auprès de GitHub avant son composer install, quand la variable CI/CD GITHUB_COM_TOKEN est exposée au job. Objectif : sortir du quota anonyme de l'API GitHub, partagé avec tous les projets qui tournent sur la même IP de runner (60 requêtes/h par IP, contre 5000/h par jeton).
Les archives dist de composer.lock pointent en effet sur api.github.com/repos/…/zipball/…, que GitHub redirige vers codeload.github.com — l'installation est donc soumise à ce quota (cf. Le mode dégradé n'est pas sûr).
if [ -n "${GITHUB_COM_TOKEN:-}" ]; then
code="$(curl -s -o /dev/null -w '%{http_code}' --connect-timeout 5 --max-time 10 \
-H "Authorization: Bearer $GITHUB_COM_TOKEN" https://api.github.com/rate_limit || true)"
if [ "$code" = "200" ]; then
if composer config --global --auth github-oauth.github.com "$GITHUB_COM_TOKEN"; then
echo "✓ Composer authentifié auprès de GitHub (quota par jeton : 5000/h, contre 60/h par IP)."
else
echo "⚠ composer config a échoué — on reste en anonyme." >&2
fi
else
echo "⚠ contrôle du jeton : api.github.com a répondu « $code » — on reste en anonyme." >&2
echo " 401 ou 403 = jeton refusé, à renouveler · 000 = injoignable ou délai dépassé." >&2
fi
fi
Portée : un seul point d'insertion¶
Aucun job ne déclare cette authentification pour son compte. Tous ceux qui installent des dépendances héritent du même before_script :
| Job | Mécanisme d'héritage |
|---|---|
build:vendor, quality:cs-fix |
extends: .php_quality_job |
security:composer-audit, tools:version-check |
extends: .php_quality_job |
quality:phpstan, quality:lint |
!reference [.php_quality_job, before_script] via .php_phpstan_job |
test:unit |
!reference [.php_quality_job, before_script] via .php_test_job |
test:e2e |
!reference [.php_quality_job, before_script] via .php_e2e_job |
Les jobs qui n'installent aucune dépendance PHP n'héritent pas de ce before_script, et c'est cohérent :
test:bashexécutebatset n'appelle jamais Composer — il n'a d'ailleurs aucunbefore_script(cf. Jobtest:bash) ;quality:composer-auditlancecomposer audit --no-interaction --locked, qui litcomposer.locksans installervendor/(cf. Jobquality:composer-audit) ;quality:ts-check,quality:shellcheck,quality:docs-build,quality:docs-a11yetquality:confinementne touchent pas à Composer.
Comportement selon l'état du jeton¶
Le bloc est fail-open : dans tous les cas d'échec, le job retombe sur le comportement qu'il avait avant l'ajout, c'est-à-dire un téléchargement anonyme.
| Situation | Ce qui se passe | Effet sur le job |
|---|---|---|
GITHUB_COM_TOKEN absent ou vide (fork, variable non exposée) |
Le bloc if n'est pas entré. |
Aucun — installation anonyme. |
api.github.com/rate_limit répond 200 et composer config réussit |
Le jeton est écrit dans le auth.json global du conteneur de job. |
Installation authentifiée (5000 requêtes/h). |
api.github.com/rate_limit répond 401 / 403 (jeton refusé ou expiré) |
Message d'avertissement sur stderr, jeton non installé. |
Aucun — installation anonyme. |
curl échoue ou dépasse --connect-timeout 5 / --max-time 10 (code 000) |
Idem, borné à ~10 s. | Aucun — installation anonyme. |
composer config échoue |
Message d'avertissement, on n'interrompt pas le before_script. |
Aucun — installation anonyme. |
Le jeton est mesuré avant d'être installé : un PAT expiré poserait un 401 sur toutes les requêtes GitHub, soit strictement pire que l'anonyme. Ce cas n'est pas théorique — c'est ce qui a déjà bloqué les MRs Renovate, où dependencies:renovate a son propre préflight de jeton (cf. .gitlab/ci/dependencies.yml).
Limite connue : la redirection cross-host¶
Depuis la version 7.58, curl retire l'en-tête Authorization sur une redirection vers un autre hôte. L'authentification porte donc sur le hop api.github.com, pas sur codeload.github.com vers lequel GitHub redirige la récupération de l'archive. Conséquence à garder en tête : si l'étranglement observé vient de codeload.github.com lui-même, ce correctif ne changera rien aux échecs. Il retire une cause probable, il ne garantit pas la fin des échecs composer install.
Où vit le jeton pendant le job¶
composer config --global --auth écrit dans le auth.json global du conteneur de job ($HOME/.composer/auth.json) — hors des cache.paths (vendor/, var/tailwind/) et hors artefacts. Il n'est donc jamais persisté dans le cache partagé du runner. Côté trace, la variable est déclarée masked dans GitLab, et les commandes qui la reçoivent en argument vivent dans un bloc - | dont GitLab n'affiche que la première ligne. Fiche de la variable : Variables CI/CD GitLab.
Repli sur la source git (--prefer-source)¶
Toujours dans le before_script de .php_quality_job (.gitlab-ci.yml), après le bloc d'authentification : le composer install est encadré pour retomber sur un clone git quand l'archive dist est indisponible.
set +e
composer install --no-interaction --prefer-dist --no-progress
_composer_rc=$?
set -e
if [ "$_composer_rc" -eq 100 ]; then
echo "⚠ Archive 'dist' indisponible (exit 100) — repli sur la source git." >&2
composer install --no-interaction --prefer-source --no-progress
elif [ "$_composer_rc" -ne 0 ]; then
echo "✗ composer install a échoué (exit $_composer_rc) — pas un problème de miroir." >&2
exit "$_composer_rc"
fi
Code de sortie du premier composer install |
Ce qui se passe |
|---|---|
0 |
Rien de plus — installation depuis les archives dist. |
100 (dependency resolution / download error) |
Second composer install --prefer-source, qui clone chaque paquet depuis git. Le job est plus lent ; il n'est plus rouge pour une raison sans rapport avec le code de la MR. |
| Tout autre code non nul | Le before_script s'arrête et propage le code tel quel. |
Deux choix de conception à ne pas défaire par inadvertance :
- Le repli vit dans la CI, pas dans
composer.json. Basculer"preferred-install"changerait le mode d'installation de tous les environnements — dev et prod compris — pour un problème qui ne se manifeste qu'en CI. - Le repli est borné au code
100. C'est le seul que produise une archive indisponible. Sans ce bornage, uncomposer.lockdésynchronisé ou un conflit de contraintes — qui échouerait à l'identique en source — paierait une seconde installation complète avant de mourir.
Conséquence côté cache : un repli en source laisse un .git dans chaque paquet installé. build:vendor les supprime avant de pousser le cache (cf. Purge de vendor/**/.git).
Voir aussi¶
- Bootstrapper la pipeline CI — séquence d'actions manuelles pour amorcer la pipeline sur une nouvelle instance GitLab (DNS, PAT, variable CI/CD, custom domain Pages, schedule, premier build des images).
- Variables d'environnement — Variables CI/CD GitLab — détail de
GITLAB_TOKENet des variables injectées par GitLab. - Créer un tag de release — procédure opérationnelle.
- Configurer l'audit de sécurité quotidien — création de la schedule GitLab qui déclenche
security:composer-audit,dependencies:renovate,tools:version-check,container_scanning(+:builders) etsecurity:container-issue(+:builders). - Configurer le rebuild hebdomadaire de la doc — schedule GitLab dédiée qui réveille
pagesavecREBUILD_DOCS=true. - Configurer les montées de version automatiques (Renovate) — réutilisation du
GITLAB_TOKEN,renovate.json, comportement des MRs. - Configurer le domaine GitLab Pages — DNS, certificat Let's Encrypt.
- Exécuter les tests — lancer la suite en local ; l'unique gate de couverture porté par
test:uniten CI (lignes 100 %) et le contrôle de branches, qui reste local. - Commandes Castor — cibles locales qui exécutent le même enchaînement que la CI (
castor all). - Le coût réel d'une pipeline CI — ce que la mesure établit sur le découpage des
changes:par suite et sur le cache du runner. - Supply chain et signatures — pourquoi signer
kirexo-prodet publier un SBOM, chaîne de confiance Fulcio / Rekor. - Déployer Kirexo en production — Vérifier la signature de l'image avant de la pull — procédure côté serveur de production.