Aller au contenu

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 — jobs release:bundle-render, release:bundle-publish et bloc release.assets.links de release: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'installation install/.

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_path commence par / et ne contient aucun numéro de version : c'est ce qui rend le permalien latest constant 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: package classe les trois fichiers d'installation dans la catégorie « Packages » de la release ; other pour 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é filepath est 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 :

sh infra/release/publish-bundle.sh render 0.0.1 var/release-assets

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