Assets de release et permaliens¶
Référence des fichiers publiés avec chaque release GitLab de Kirexo : où ils sont stockés, sous quelles URL on les télécharge, comment KIREXO_VERSION est écrite dans le .env.example publié, et ce que fait le script qui les rend puis les envoie.
Sources :
.gitlab/ci/release.yml— jobsrelease:bundle-render,release:bundle-publishet blocrelease.assets.linksderelease:create;infra/release/publish-bundle.sh— orchestrateur (rendu, envoi) ;infra/release/release-bundle.lib.sh— fonctions pures : nom du paquet, liste des fichiers, URL, substitution ;install/compose.yaml,install/.env.example,install/README.md— sources du bundle d'installation, décrites dans Bundle d'installationinstall/.
Le détail des jobs (image, needs, déclencheurs) est dans Pipeline GitLab CI — Release.
Paquet générique kirexo¶
Les assets ne sont pas des artifacts de job : ils sont publiés dans le Generic Package Registry du projet, qui n'applique aucune expiration. Un artifact expire (expire_in) et peut être supprimé à la main ; un permalien de téléchargement qui pointerait dessus finirait en 404.
| Propriété | Valeur |
|---|---|
| Registry | Generic Package Registry du projet GitLab |
| Nom du paquet | kirexo — source unique : release_bundle_package_name |
| Version du paquet | le tag de release, $CI_COMMIT_TAG (ex. 0.0.1) |
| URL d'un fichier | ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/kirexo/<version>/<fichier> |
| Authentification à l'envoi | en-tête JOB-TOKEN: ${CI_JOB_TOKEN} |
| Expiration | aucune |
L'URL d'un fichier est produite par release_bundle_package_url : simple concaténation, sans encodage, les noms de fichiers ne contenant que [A-Za-z0-9._-].
Cinq ou sept assets¶
Liste et ordre fixés par release_bundle_assets ; upload publie dans cet ordre : les trois fichiers d'installation, les deux SBOM linux/amd64 de l'image kirexo-prod (SPDX puis CycloneDX), puis, seulement si l'image arm64 a été publiée, les deux SBOM linux/arm64 (SPDX puis CycloneDX).
| Release | Fichiers | Condition |
|---|---|---|
linux/amd64 seule |
5 : 3 d'installation + 2 SBOM amd64 | KIREXO_PROD_ARM64_BUILT absente ou différente de true |
linux/amd64 + linux/arm64 |
7 : 3 d'installation + 2 SBOM amd64 + 2 SBOM arm64 | KIREXO_PROD_ARM64_BUILT=true |
release_bundle_assets lit KIREXO_PROD_ARM64_BUILT dans l'environnement : seule la valeur littérale true ajoute les deux SBOM arm64. La variable vient du dotenv de docker:manifest-prod (cf. Job docker:manifest-prod).
| Fichier du paquet | Source | Nom du lien de release | direct_asset_path |
link_type |
Posé par |
|---|---|---|---|---|---|
compose.yaml |
install/compose.yaml, copié tel quel |
Installation — compose.yaml |
/compose.yaml |
package |
release:create |
.env.example |
install/.env.example, rendu (cf. Substitution de KIREXO_VERSION) |
Installation — .env.example |
/.env.example |
package |
release:create |
README.md |
install/README.md, copié tel quel |
Installation — README.md |
/README.md |
package |
release:create |
sbom-kirexo-prod-<version>-linux-amd64.spdx.json |
artifact de release:sbom |
SBOM linux/amd64 (SPDX JSON) |
/sbom/kirexo-prod-linux-amd64.spdx.json |
other |
release:create |
sbom-kirexo-prod-<version>-linux-amd64.cdx.json |
artifact de release:sbom |
SBOM linux/amd64 (CycloneDX JSON) |
/sbom/kirexo-prod-linux-amd64.cdx.json |
other |
release:create |
sbom-kirexo-prod-<version>-linux-arm64.spdx.json — si arm64 publié |
artifact de release:sbom |
SBOM linux/arm64 (SPDX JSON) |
/sbom/kirexo-prod-linux-arm64.spdx.json |
other |
release:links-arm64 |
sbom-kirexo-prod-<version>-linux-arm64.cdx.json — si arm64 publié |
artifact de release:sbom |
SBOM linux/arm64 (CycloneDX JSON) |
/sbom/kirexo-prod-linux-arm64.cdx.json |
other |
release:links-arm64 |
Les deux liens arm64 ne figurent pas dans le bloc release.assets.links de release:create : ce bloc est statique et ne peut pas rendre un lien conditionnel. release:links-arm64 les ajoute une fois la release créée, par l'API Release Links, avec les mêmes noms, URL et direct_asset_path (cf. Job release:links-arm64).
Règles :
- chaque
direct_asset_pathcommence par/et ne contient aucun numéro de version : c'est ce qui rend le permalienlatestconstant d'une release à l'autre ; - le nom de fichier des SBOM garde la version et l'architecture, pour rester identifiable une fois téléchargé ;
- chaque SBOM décrit une image de plateforme, scannée par son digest : aucun SBOM ne décrit l'index multi-architecture dans son ensemble (cf. Job
release:sbom) ; link_type: packageclasse les trois fichiers d'installation dans la catégorie « Packages » de la release ;otherpour les SBOM, faute de catégorie SBOM ;- noms de liens et URL sont uniques dans une release (contrainte de l'API Release Links) ;
- la clé s'appelle
direct_asset_path. L'ancienne cléfilepathest dépréciée et n'est jamais utilisée.
Pas de permalien SBOM sans architecture
Aucun direct_asset_path SBOM ne s'écrit sans suffixe d'architecture, et aucun alias ne redirige un tel chemin vers l'un des SBOM par architecture. Un permalien SBOM sans architecture n'a jamais été publié : aucune release semver n'a précédé l'image multi-architecture, et les releases horodatées antérieures ne déclaraient aucun direct_asset_path. Un alias vers le SBOM amd64 laisserait en outre croire qu'un SBOM unique décrit l'image publiée, ce qui est faux.
Permaliens¶
GitLab sert un lien de release à une URL stable dérivée de son direct_asset_path, puis redirige vers l'URL du lien, c'est-à-dire vers le fichier du paquet.
| Forme | URL | Usage |
|---|---|---|
| Dernière release | https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/<chemin> |
installation |
| Release précise | https://gitlab.com/shaurifr/kirexo/-/releases/<tag>/downloads/<chemin> |
mise à jour vers une version donnée, restauration, retour arrière |
<chemin> est le direct_asset_path sans son / initial. Permaliens de la dernière release :
| Asset | Permalien |
|---|---|
compose.yaml |
https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/compose.yaml |
.env.example |
https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/.env.example |
README.md |
https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/README.md |
SBOM linux/amd64 SPDX |
https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/sbom/kirexo-prod-linux-amd64.spdx.json |
SBOM linux/amd64 CycloneDX |
https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/sbom/kirexo-prod-linux-amd64.cdx.json |
SBOM linux/arm64 SPDX |
https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/sbom/kirexo-prod-linux-arm64.spdx.json |
SBOM linux/arm64 CycloneDX |
https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/sbom/kirexo-prod-linux-arm64.cdx.json |
Les deux permaliens linux/arm64 n'existent que pour une release dont l'image arm64 a été publiée. Pour une release linux/amd64 seule, ils ne sont pas posés, et les permaliens latest correspondants ne mènent à aucun fichier tant que la dernière release reste linux/amd64 seule. La note de release le signale par une section « Architecture ».
Exemple de forme par version : https://gitlab.com/shaurifr/kirexo/-/releases/0.0.1/downloads/compose.yaml.
Les commandes curl -fsSLO de install/README.md et des pages d'auto-hébergement de la documentation citent ces URL caractère pour caractère. Changer un direct_asset_path dans .gitlab/ci/release.yml impose de changer le README et ces pages, et inversement (cf. URL figées).
Ce que désigne latest¶
latest est la release dont la date de publication (released_at) est la plus récente, et non celle qui porte la plus grande version. GitLab ne propose pas de tri par version sémantique pour ce permalien.
| Situation | Release désignée par latest |
|---|---|
Releases publiées dans l'ordre des versions (0.1.0, puis 0.2.0) |
0.2.0 |
Correctif d'une ancienne ligne publié après une version plus haute (0.2.0, puis 0.1.5) |
0.1.5 |
Release dont released_at est dans le futur (« Upcoming ») |
jamais elle ; la précédente reste latest |
Tant que le projet ne maintient qu'une seule ligne de versions, les deux ordres coïncident. Publier un correctif sur une ligne antérieure déplacerait les permaliens latest, donc la version installée par une installation neuve.
Téléchargement anonyme¶
Le projet est public, mais l'accès sans jeton à un fichier de paquet générique dépend du niveau d'accès du Package Registry du projet (package_registry_access_level). Un permalien qui renvoie 401 ou 404 sans jeton alors que le fichier existe dans le paquet relève de ce réglage, pas de la release.
Substitution de KIREXO_VERSION¶
Le .env.example publié cite toujours exactement la version du tag qui l'accompagne. Le fichier versionné install/.env.example porte une valeur de référence ; la pipeline de tag la remplace dans la copie publiée. La valeur n'est jamais maintenue à la main et n'est jamais un tag flottant.
Règle appliquée par release_bundle_render_env <version> (filtre entrée standard → sortie standard) :
| Ligne lue | Ligne écrite |
|---|---|
commence, en colonne 1, par KIREXO_VERSION= (quelle que soit la valeur, vide comprise) |
KIREXO_VERSION=<version> — la ligne entière est remplacée |
# KIREXO_VERSION=… (commentée) |
inchangée |
XKIREXO_VERSION=…, ou toute autre ligne |
inchangée |
- Un commentaire en fin de ligne (
KIREXO_VERSION=0.0.1 # …) est perdu : il doit être placé sur les lignes précédentes. - L'ordre des lignes et les lignes vides sont conservés. Une dernière ligne sans saut de ligne final est lue ; en sortie, chaque ligne se termine par un saut de ligne.
- Le nombre de lignes remplacées doit valoir exactement 1 :
Lignes KIREXO_VERSION= |
Résultat | Message (sortie d'erreur) |
|---|---|---|
| 0 | échec | aucune ligne KIREXO_VERSION= dans .env.example : la version ne peut pas être épinglée |
| 1 | succès | — |
| N > 1 | échec | N lignes KIREXO_VERSION= dans .env.example : ambigu |
Garde-fou côté compose.yaml : release_bundle_compose_pins_version exige que install/compose.yaml contienne la chaîne ${KIREXO_VERSION. Sinon l'image serait épinglée en dur dans le Compose et la substitution du .env.example n'aurait aucun effet. Message : compose.yaml ne référence pas ${KIREXO_VERSION} : l'image n'est pas paramétrée par la version.
La version elle-même est validée par release_bundle_is_semver : exactement ^[0-9]+\.[0-9]+\.[0-9]+$, le motif des rules: de tag de la pipeline. Refusés : préfixe v, suffixe (-rc1), quatrième composante, composante vide (0..1, .0.1, 0.0.), espace, chaîne vide, ancien tag horodaté.
infra/release/publish-bundle.sh¶
Usage : sh infra/release/publish-bundle.sh render <version> <dossier-sortie>
sh infra/release/publish-bundle.sh upload <version> <dossier>
Exit : 0 = succès · 1 = rendu ou publication en échec · 2 = usage invalide / prérequis absent
Script POSIX sh (les images Alpine des jobs n'ont pas bash), en set -eu. La lib release-bundle.lib.sh est chargée relativement au script, jamais par /app. -h ou --help affiche l'usage sur la sortie standard et sort en 0.
Contrôles communs, avant toute action :
| Cas | Code |
|---|---|
| Nombre d'arguments différent de 3, sous-commande inconnue, dossier vide | 2, usage sur la sortie d'erreur |
Version refusée par release_bundle_is_semver |
2, Version invalide « <v> » : attendu MAJEUR.MINEUR.CORRECTIF (ex. 0.0.1, sans préfixe v). |
render <version> <dossier-sortie>¶
Les sources sont lues dans install/ à la racine du dépôt, déduite de l'emplacement du script (<script>/../..) et non du répertoire courant. Le dossier de sortie, lui, est relatif au répertoire courant.
| Étape | Échec |
|---|---|
1. Présence de install/compose.yaml, install/.env.example, install/README.md |
2 — une ligne Source manquante : install/<fichier> par fichier absent, tous listés |
2. install/compose.yaml référence ${KIREXO_VERSION |
1 |
3. Création du dossier, copie de compose.yaml et README.md, rendu de .env.example |
1 — le .env.example partiel est supprimé |
4. Ligne ✓ Bundle rendu dans <dossier> (KIREXO_VERSION=<version>) |
— |
render ne lit aucune variable CI et n'utilise pas le réseau. Il se rejoue dans le conteneur php :
upload <version> <dossier>¶
| Étape | Échec |
|---|---|
1. CI_API_V4_URL, CI_PROJECT_ID, CI_JOB_TOKEN non vides |
2 — Variable CI manquante : <NOM> (upload réservé au job release:bundle-publish). La valeur n'est jamais affichée |
2. curl présent dans le PATH |
2 — curl introuvable dans le PATH. |
3. Les cinq ou sept fichiers de release_bundle_assets <version> existent dans le dossier, avant tout envoi |
2 — une ligne Fichier manquant : <dossier>/<fichier> par absent ; aucun fichier envoyé |
| 4. Envoi de chaque fichier, dans l'ordre de la liste | 1 au premier échec — ligne ✗ <fichier> suivie du corps de réponse de l'API ; les fichiers suivants ne sont pas envoyés |
Commande d'envoi, par fichier :
curl --fail-with-body --silent --show-error --retry 3 \
--header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
--upload-file "<dossier>/<fichier>" "<url du fichier dans le paquet>"
Sortie nominale : Publication du paquet kirexo/<version>, puis une ligne ✓ <fichier> par fichier. Le script n'active jamais set -x et n'affiche ni l'en-tête ni la commande : le jeton n'apparaît pas dans la trace.
Relancer release:bundle-publish
Envoyer un fichier déjà présent au même nom et à la même version ajoute un fichier au paquet ; le téléchargement sert le plus récent. Relancer le job est donc sans effet sur les URL, au prix de doublons dans le paquet. L'interdiction des doublons de paquets génériques ne doit pas être activée : elle ferait échouer toute relance.
Rendu et publication : deux jobs¶
| Job | Sous-commande | Produit |
|---|---|---|
release:bundle-render |
render "$CI_COMMIT_TAG" release-assets, puis copie des SBOM de release:sbom dans release-assets/, nommés un par un : les deux amd64 toujours, les deux arm64 seulement si KIREXO_PROD_ARM64_BUILT=true |
artifact release-assets/ (cinq ou sept fichiers), conservé 1 semaine |
release:bundle-publish |
upload "$CI_COMMIT_TAG" release-assets |
les cinq ou sept fichiers dans le paquet kirexo/<version> |
Le rendu et l'envoi sont séparés pour qu'un contrôle portant sur l'artifact rendu puisse s'intercaler avant que les fichiers ne soient publiés. release:bundle-render n'envoie rien ; release:bundle-publish ne rend rien.
La copie des SBOM nomme les deux ou quatre fichiers un par un, sans motif générique : un SBOM absent fait échouer le cp, donc le job. Les SBOM amd64 sont exigés sans condition.
release:bundle-render attend docker:manifest-prod, avec ses artifacts pour lire KIREXO_PROD_ARM64_BUILT : le .env.example rendu cite KIREXO_VERSION=<version>, et l'image kirexo-prod:<version> n'existe qu'une fois l'index assemblé. release:bundle-publish attend aussi docker:manifest-prod (même dotenv, qui décide de la liste de release_bundle_assets) et docker:sign-prod : le paquet, lisible sans jeton, n'est publié qu'une fois l'image signée et vérifiée.
release:create attend release:bundle-publish et docker:sign-prod : si l'envoi ou la signature échoue, aucune release n'est créée, et aucune release ne pointe donc vers un paquet incomplet ou une image non signée. release:links-arm64 attend release:create pour y ajouter, le cas échéant, les deux liens arm64.
Voir aussi¶
- Pipeline GitLab CI — Release — image,
needset déclencheurs de chaque job. - Bundle d'installation
install/— contenu des trois fichiers d'installation et règles de maintenance du README. - Déployer Kirexo en production — SBOM disponible en asset de la release — récupérer les SBOM.
- Supply chain et signatures — pourquoi publier un SBOM.