Bootstrapper la pipeline CI¶
Tu installes Kirexo sur une nouvelle instance GitLab (fork, miroir, nouveau namespace) et tu veux que la pipeline CI tourne complètement : quality, tests, builds Docker, publication de la doc sur https://doc.kirexo.app/, schedule de maintenance quotidienne (Renovate, audit Composer, scan CVE, version-check d'outils).
Cette page enchaîne dans l'ordre les actions manuelles à réaliser. Chaque étape débloque la suivante — ne pas en sauter. Le détail de chaque sous-procédure est documenté ailleurs ; cette page-ci sert d'index séquentiel.
Prérequis¶
- Tu as les droits Maintainer ou Owner sur le projet GitLab.
- Tu as accès à la zone DNS de
kirexo.app(registrar, panneau Cloudflare, etc.). - Le code Kirexo est déjà poussé sur la branche
maindu projet GitLab cible (la pipeline ne peut pas tourner si le repo est vide).
Prérequis : un runner tagué kirexo-self
Tous les jobs héritent de default: tags: [kirexo-self] (.gitlab-ci.yml). Sans runner en ligne portant ce tag, toute pipeline reste pending : aucun job ne se replie sur les runners hébergés par GitLab. Enregistre un runner de projet amd64, puis ajoute-lui le tag : Settings › CI/CD › Runners, éditer le runner de projet, champ Tags → ajouter kirexo-self en conservant les tags existants, sans toucher aux autres options.
La pose est à refaire si le runner est réenregistré. Sur ce projet, le runner est 53537908 ; sur une autre instance, ce sera l'identifiant de ton runner. Variante par API (attention : tag_list remplace la liste) et vérification a posteriori : Runners.
Vue d'ensemble¶
| Étape | Action | Débloque |
|---|---|---|
| 1 | Réserver doc.kirexo.app dans la zone DNS |
Étape 4 (custom domain Pages) |
| 2 | Créer le Personal Access Token GITLAB_TOKEN |
Étape 3 |
| 3 | Configurer la variable CI/CD GITLAB_TOKEN (masked, non protected) |
Étapes 4 et 5 |
| 4 | Associer le domaine doc.kirexo.app à GitLab Pages |
Publication de la doc sur l'URL canonique |
| 5 | Créer la schedule cron 0 5 * * * sur main |
Audit Composer + Renovate + tools:version-check + scan CVE quotidiens |
| 6 | Bootstrap manuel : ▶ sur docker:build-base, puis build + push de kirexo-dev depuis l'hôte |
Tous les jobs PHP (quality:*, test:*) |
| 7 | Activer la cleanup policy du Container Registry | Empêche les tags de version kirexo-prod:<x.y.z> de s'accumuler indéfiniment au fil des releases |
Étape 1 — Réserver le DNS doc.kirexo.app¶
Préalable à toute association de custom domain côté GitLab Pages. Si l'enregistrement DNS n'existe pas, la vérification de propriété (étape 4) échoue immédiatement.
Dans le panneau DNS de ton registrar, crée un enregistrement CNAME :
| Type | Nom | Valeur |
|---|---|---|
CNAME |
doc |
<namespace>.gitlab.io. (le point final est important — shaurifr.gitlab.io. pour l'instance de référence) |
Cloudflare : DNS only
Si la zone est gérée par Cloudflare, mets l'enregistrement en mode DNS only (nuage gris). Le proxy Cloudflare casserait le challenge Let's Encrypt à l'étape 4.
La propagation DNS prend de quelques minutes à 24 h selon le TTL — autant la lancer au plus tôt.
Vérifier la propagation
Attendu : la valeur duCNAME cible. Tant que la commande ne renvoie rien, l'étape 4 échouera.
Étape 2 — Créer le Personal Access Token GITLAB_TOKEN¶
Le token est utilisé par quatre jobs CI : tag:create (création de tag), security:composer-audit (MR de patch sécurité ou issue de fallback), tools:version-check (issue de retard d'outils) et dependencies:renovate (ouverture des MRs Renovate).
PAT et pas project access token
Sur GitLab.com tier gratuit, les project access tokens sont réservés à Premium/Ultimate. Le seul type de token utilisable en variable CI/CD est un Personal Access Token rattaché à un compte ayant au moins le rôle Maintainer sur le projet.
- Sur le compte propriétaire, aller dans User Settings → Access Tokens.
- Cliquer sur Add new token.
-
Renseigner :
Champ Valeur Token name kirexo-ci(ou ce que tu veux)Expiration date une date dans 1 an max (GitLab impose une expiration) Scopes api+write_repository -
Cliquer sur Create personal access token.
- Copier la valeur affichée immédiatement — GitLab ne la ré-affichera plus.
Les deux scopes sont obligatoires
apicouvre la création d'issues et de merge requests (security:composer-auditen fallback,tools:version-check, Renovate qui ouvre les MRs).write_repositorycouvre la création de branches et de tags : requis parsecurity:composer-auditquand l'update résout les vulnérabilités (il pousse une branchesecurity/composer-*puis ouvre la MR), partag:create(création du tag de release) et par Renovate (création des branchesrenovate/*).
Un token porteur du seul scope api fait tourner la pipeline tant qu'aucun job ne pousse de référence. Dès que security:composer-audit tente le git push de sa branche de patch, il échoue sur 403 Forbidden si write_repository manque.
Étape 3 — Configurer la variable CI/CD GITLAB_TOKEN¶
- Dans le projet GitLab cible, aller dans Settings → CI/CD → Variables.
- Cliquer sur Add variable.
-
Renseigner :
Champ Valeur Type VariableEnvironments All (default)Visibility MaskedFlags Protect variabledécochéKey GITLAB_TOKENValue (la valeur PAT copiée à l'étape 2) -
Cliquer sur Add variable.
Masked oui, Protected non
- Mask doit être coché : sans lui, le token apparaît en clair si un job l'
echopar mégarde dans son log. - Protect doit rester décoché :
security:container-issue(+:builders) tourne sur la pipeline de la MR / feature branch courante pour ouvrir l'issue d'alerte CVE, etProtect variablerendraitGITLAB_TOKENindisponible sur ces refs non protégées — l'appelPOST /projects/:id/issuespartirait sansPRIVATE-TOKENet retomberait en HTTP 401.
Si Mask refuse la valeur (« value does not meet the masking requirements »), regénère le PAT — sa valeur contient probablement un caractère interdit (rare avec les PATs récents).
Détail complet et liste des jobs qui consomment ce token : voir Variables CI/CD GitLab.
Les jobs security:container-issue réutilisent le même GITLAB_TOKEN
Les deux jobs d'alerting CVE conteneur (security:container-issue et security:container-issue:builders) s'authentifient via GITLAB_TOKEN (PRIVATE-TOKEN), le même PAT que celui que tu viens de configurer pour security:composer-audit, tools:version-check et Renovate. Aucune variable supplémentaire à provisionner, et aucun pré-requis Token Access à activer pour ce projet : on n'utilise pas CI_JOB_TOKEN ici parce que sa whitelist sur GitLab Free ne couvre pas POST /projects/:id/issues (retour HTTP 401 testé empiriquement). Le scope api du PAT déjà créé suffit.
Étape 4 — Configurer le custom domain GitLab Pages¶
L'enregistrement DNS de l'étape 1 doit avoir propagé (vérifier avec dig +short CNAME doc.kirexo.app).
Suivre la procédure complète dans Configurer le domaine GitLab Pages : déclaration du domaine, enregistrement TXT de vérification, certificat Let's Encrypt, Force HTTPS.
La première release peut attendre
GitLab Pages affiche un 404 tant que le job pages n'a pas tourné au moins une fois. C'est attendu — le bootstrap final (étape 6) ne crée pas de release ; la première vraie URL https://doc.kirexo.app/ n'apparaîtra qu'après ton premier tag (le job pages du stage release ne tourne que sur tag — cf. Créer un tag de release).
Étape 5 — Créer la schedule cron 0 5 * * * sur main¶
Cette unique schedule déclenche tous les jobs périodiques du stage maintenance : security:composer-audit, dependencies:renovate, tools:version-check, container_scanning (kirexo-prod), container_scanning:builders (kirexo-base, kirexo-dev) et leurs jobs d'alerting (security:container-issue, security:container-issue:builders).
Suivre la procédure dans Configurer l'audit de sécurité quotidien — schedule unique 0 5 * * * sur main, sans variable additionnelle.
Tester immédiatement
Une fois la schedule créée, clique sur l'icône ▶ à droite. La pipeline se lance avec $CI_PIPELINE_SOURCE == "schedule" exactement comme à 5 h UTC. Tu peux ainsi valider en quelques minutes que GITLAB_TOKEN a les bons scopes (sinon security:composer-audit échoue sur 403 Forbidden au git push, et Renovate sur 401 à l'ouverture de MR).
Étape 6 — Bootstrap manuel des images kirexo-base et kirexo-dev¶
C'est la dernière étape — et la plus facile à oublier. Sans ces deux images dans le registry, tous les jobs PHP de la pipeline standard plantent immédiatement sur ErrImagePull (l'image qu'ils consomment n'existe pas). Le commentaire en tête de .gitlab-ci.yml rappelle ce prérequis.
Les deux images ne se bootstrappent pas de la même façon :
docker:build-baseest manuel surmainet ne dépend d'aucun job (needs: []) : son bouton ▶ reste utilisable même quand les jobs PHP échouent.docker:build-devn'a pas de bouton ▶. Il ne part surmainqu'après des stagesqualityettestverts, ce qui est impossible tant quekirexo-devmanque. Sa première publication se fait donc depuis l'hôte.
6.a — Publier kirexo-base depuis la CI¶
- Dans le projet GitLab, aller dans Build → Pipelines.
- Cliquer sur Run pipeline (en haut à droite).
- Branche cible :
main. Pas de variable à passer. Cliquer sur Run pipeline. - Sur la page de la pipeline qui démarre, repérer le stage
docker. Les jobsquality:*ettest:*échouent surErrImagePull: c'est attendu. - Cliquer sur le bouton ▶ (manuel) du job
docker:build-base. Attendre sa fin (vert).
6.b — Construire et pousser kirexo-dev depuis l'hôte¶
Dans un terminal côté hôte, à la racine du dépôt, sur un checkout à jour de main :
docker login registry.gitlab.com
docker build \
--target frankenphp_dev \
--build-arg BUILD_REF=$(git rev-parse --short HEAD) \
-t registry.gitlab.com/shaurifr/kirexo/kirexo-dev:php8.5-alpine \
.
docker push registry.gitlab.com/shaurifr/kirexo/kirexo-dev:php8.5-alpine
docker login demande ton identifiant GitLab et un Personal Access Token autorisé à écrire dans le registry. Sur une autre instance que l'instance de référence, remplace registry.gitlab.com/shaurifr/kirexo par la valeur de $CI_REGISTRY_IMAGE du projet. BUILD_REF alimente /etc/kirexo-dev.ref (cf. Image de développement kirexo-dev).
6.c — Valider¶
Relancer Run pipeline sur main. Les jobs PHP doivent maintenant démarrer. Si quality et test passent, docker:build-dev reconstruit l'image dans la foulée : une pipeline web évalue toujours ses changes à vrai. Cette seconde publication remplace l'image poussée depuis l'hôte par une image construite en CI.
Pourquoi pas un bouton ▶ sur docker:build-dev
Le job est automatique et sans needs pour ne jamais publier une image dev depuis un main rouge. Le détail est dans Chaînage docker:build-base → dev / prod. Les pipelines lancées par l'API (glab ci run) ne le créent pas non plus : seul Run pipeline dans l'UI (source web) déclenche une reconstruction ponctuelle.
Premier build sur base Alpine : compte un temps plus long
L'image de Kirexo est bâtie sur Alpine (cf. Pourquoi une image Alpine multi-stage). Le tout premier docker:build-base reconstruit intégralement les layers (extensions PHP via install-php-extensions, résolution des libs musl) sans cache disponible — compte une durée sensiblement plus longue à ce passage inaugural. Les builds suivants réutilisent le cache --cache-from du dernier :php8.5-alpine publié et redeviennent rapides.
Pas besoin de bootstrapper kirexo-prod ni kirexo-docs
kirexo-prodest construite automatiquement au premier tag de release, en amd64 pardocker:build-prodet en arm64 pardocker:build-prod-arm64, puis assemblée en index pardocker:manifest-prod. Le runner arm64 est un runner hébergé par GitLab (saas-linux-small-arm64) : rien à enregistrer. La jambe arm64 est best-effort : si elle échoue ou ne démarre pas (quota de minutes CI épuisé), l'index ne contient quelinux/amd64et la release le signale dans sa note. Elle n'est consommée par aucun job de runner CI — uniquement par la prod viacompose.prod.yaml.kirexo-docsest construite automatiquement pardocker:build-docssurmain(quandmkdocs/Dockerfilechange) ou au tag de release, avant le jobpagesqui la consomme. Aucun bootstrap manuel requis.
Étape 7 — Activer la cleanup policy du Container Registry¶
À chaque tag de release, la pipeline publie une nouvelle image kirexo-prod:<x.y.z> et ses tags d'architecture :<x.y.z>-amd64 et, si la jambe arm64 a poussé, :<x.y.z>-arm64 (~150-300 Mo par architecture), en plus de réécrire le tag mobile :latest. Sans nettoyage, le registry accumule deux tags par release sans arm64, trois avec, sans limite. Autant configurer la politique de cleanup dès le bootstrap, avant la première release — elle s'appliquera au fur et à mesure que les tags arrivent, sans rien à modifier plus tard.
La procédure (paramètres UI exacts à saisir, choix de regex, comportement combiné Keep/Remove) est documentée séparément : Configurer la cleanup policy du registry.
Politique recommandée en résumé :
| Champ | Valeur |
|---|---|
| Remove tags matching | (?:[0-9]+\.[0-9]+\.[0-9]+(?:-(?:amd64\|arm64))?\|[0-9]{12}) — versions sémantiques, tags d'architecture X.Y.Z-amd64 / X.Y.Z-arm64 et anciens tags horodatés. GitLab ancre le motif lui-même : pas de ^ ni de $. |
| Keep the most recent | 30 tags per image name |
| Keep tags matching | latest |
| Run cleanup | Every week |
Les autres images (kirexo-base, kirexo-dev, kirexo-docs) ne sont pas affectées — elles ne reçoivent aucun tag de version, et php8.5-alpine ne matche pas le motif.
Vérification finale¶
À ce stade :
- [ ]
dig +short CNAME doc.kirexo.apprenvoie la cible GitLab Pages. - [ ] Settings → CI/CD → Variables affiche
GITLAB_TOKENenMasked(et pas enProtected). - [ ] Settings → Pages affiche
doc.kirexo.appenVerifiedavec certificat Let's Encrypt actif et Force HTTPS coché. - [ ] Build → Pipeline schedules affiche la schedule
Audit sécurité quotidien(ou son équivalent) activée surmain. - [ ] Deploy → Container Registry liste au moins
kirexo-base:php8.5-alpineetkirexo-dev:php8.5-alpine. - [ ] Settings → Packages and registries → Container registry → Cleanup policy est Enabled avec la politique recommandée.
Une nouvelle MR pousser sur main doit maintenant déclencher une pipeline complète qui passe — toute la chaîne quality + test consomme les deux images bootstrappées à l'étape 6, l'audit Composer bloquant (quality:composer-audit) consomme le token de l'étape 3, et le rebuild de doc passera dès la prochaine release sur le domaine de l'étape 4.
Signature et SBOM : pas de variable CI/CD à provisionner
Les jobs docker:sign-prod (signature keyless cosign de kirexo-prod) et release:sbom (SBOM SPDX + CycloneDX via syft) tournent automatiquement sur la première release sans configuration supplémentaire :
- Signature keyless : aucune clé privée à gérer. Le JWT OIDC est généré automatiquement par GitLab via
id_tokens.SIGSTORE_ID_TOKEN, et Fulcio / Rekor sont des services publics. Cf. Signature keyless dekirexo-prod. - SBOM : syft réutilise
CI_REGISTRY_USER/CI_REGISTRY_PASSWORDnatifs pour scanner l'image directement dans le registry. Cf. Jobrelease:sbom.
Signaux que tout fonctionne après la première release :
- [ ] Build → Pipelines :
docker:manifest-prodetdocker:sign-prodsont passés verts sur la pipeline du tag ; la trace dedocker:sign-prodaffiche sept lignes✓ signature vérifiéesidocker:build-prod-arm64est vert, cinq sinon.docker:build-prod-arm64peut échouer (allow_failure) sans bloquer la release, qui sort alors enlinux/amd64seul. - [ ] Deploy → Releases : le widget Assets de la release affiche SBOM linux/amd64 en SPDX JSON et en CycloneDX JSON, plus SBOM linux/arm64 dans les deux formats si l'image arm64 a été publiée. Sans arm64, la note de release contient une section « Architecture ».
Et après ?¶
- Premier tag de release : Créer un tag de release.
- Comportement détaillé de Renovate : Configurer les montées de version automatiques (Renovate).
- Rebuild hebdo automatique de la doc figée sur la dernière version semver : Configurer le rebuild hebdomadaire de la doc.
- Détail complet de chaque job : Référence Pipeline GitLab CI.