aggrega push
aggrega push publie une entité de catalogue dans un registre OCI, où d’autres workspaces peuvent la résoudre avec aggrega pull.
Fonctionnement
aggrega push lit un seul YAML d’entité, l’empaquette pour le transport et l’envoie vers <registry>/<kind>/<metadata.name>:<metadata.version>, avec le chemin du dépôt en minuscules ; une Recipe ou une FeatureRecipe porte sa spec.capability, et un Plugin son metadata.pluginType, sous forme de segment entre le type et le nom. Exécutez aggrega push --list-kinds pour obtenir les types d’entités que publie le binaire installé — un type par ligne, triés, et rien d’autre, de sorte qu’un script peut le lire directement. L’ensemble couvre les types de création du catalogue ainsi que l’Aggregate, un module réutilisable, et le Plugin, une référence adressée par contenu à un artefact WebAssembly que le compilateur achemine et que le runtime exécute. Le Plugin est un artefact publiable structurel plutôt qu’un type de création du catalogue. La publiabilité est une propriété de l’entité, et non de son usage : un Aggregate est publiable qu’il soit ensuite référencé comme spec.aggregate de premier niveau d’une Release ou imbriqué dans le bloc aggregates: d’un autre Aggregate. Release et Manifest sont des entrées côté déploiement, et non des artefacts de catalogue, et sont rejetés.
Empaquetage
Un push publie le document de l’entité et les fichiers que l’entité elle-même nomme à côté — et rien d’autre de son répertoire. Les fichiers que nomme une entité sont :
- pour une Recipe ou une FeatureRecipe, sa
source:locale — un répertoire est transporté avec chaque fichier qu’il contient que conservent les règles d’exclusion enregistrées dans sonentity.lock, comme le décrit Quels fichiers sont livrés avec une entité ; chaque fichier que ses entréesvaluesMapping:,workload:etartifacts:importent avec$import:; et l’entity.lockà côté d’elle ; - pour un Component ou une Feature, chaque fichier de schéma que son
spec.schema, un pilier ou un socketusesSchemaimporte avec$import:, y compris chaque fichier qu’un fichier importé importe à son tour.
Un Aggregate, un Plugin et les types de bibliothèques ne nomment aucun fichier à côté de leur document. Une note, un README, les fichiers d’une autre entité ou la sortie d’un build présents dans le répertoire ne sont pas publiés, quel que soit leur nom. Un lien symbolique parmi les fichiers que nomme une entité est refusé plutôt que suivi — A symbolic link sits among the files an entity carries (Un lien symbolique se trouve parmi les fichiers que transporte une entité) —, tout comme un chemin qu’une entité nomme à travers un répertoire qui est un lien menant hors du répertoire de l’entité, avant que quoi que ce soit ne soit empaqueté — A path names content outside the entity’s own directory (Un chemin nomme un contenu situé hors du répertoire propre de l’entité).
La forme en découle. Une entité qui ne nomme rien est publiée sous la forme de son document, inchangé, sous le type de média +yaml de son type. Une entité qui nomme un fichier est publiée sous la forme d’un .tar.gz contenant le document et ces fichiers à leur place dans le répertoire, sous le type de média +tar+gz de son type. Ainsi, une Recipe dont tout le contenu est inline est publiée sous la forme de son document, et un Component dont le schéma est importé d’un fichier est publié sous la forme d’une archive. Catalogue et registre §6 liste les deux types de média pour chaque type.
Chaque fichier d’une archive porte le mode 0644 et aucun horodatage, quels que soient ses bits de permission sur le disque. Un checkout écrit les fichiers avec ses propres bits de permission, et un système qui n’enregistre aucun bit d’exécution extrait comme fichier ordinaire ce qu’un autre système extrait comme exécutable ; l’archive ne porte donc aucun mode lu depuis le disque : deux checkouts d’un même commit publient les mêmes fichiers, quels que soient leur umask et le système sur lequel ils ont été faits, et basculer le bit d’exécution d’un script ne change rien à ce qui est publié.
Un push avertit de chaque entrée d’une archive que Windows ne peut pas contenir telle qu’elle est écrite — un chemin dont une partie porte le nom d’un périphérique, comme CON, AUX ou NUL, quelle que soit la casse et quelle que soit l’extension qui suit, comme aux/x.yaml, ou une partie se terminant par un point ou une espace, comme report.. Sous Windows, aggrega refuse de décompresser une telle entrée ; un workspace Windows ne peut donc pas utiliser la version. L’avertissement est écrit sur la sortie d’erreur standard sur chaque plateforme, une ligne par entrée, avant le compte rendu propre de la publication ; le nom de fichier du document de l’entité lui-même est évalué avec les fichiers qu’elle nomme, et une entité qui ne nomme rien est publiée sous la forme de son seul document et ne fait jamais l’objet d’un avertissement. Il ne refuse rien : le push se poursuit ou est refusé exactement comme il le serait sans lui, et --dry-run avertit de la même manière. A published archive carries an entry Windows cannot use (Une archive publiée contient une entrée que Windows ne peut pas utiliser) montre la ligne et ce qu’il faut faire.
Une source: locale écrite sous forme de template emporte tout le répertoire. Un template tel que ./charts/{{ .values.flavour }} ne nomme un répertoire qu’une fois qu’une Release le remplit ; aucune publication ne peut donc savoir lequel ce sera. Une telle entité emporte chaque fichier de son propre répertoire que conservent ses règles d’exclusion enregistrées — jamais son .aggregaignore, dont les règles voyagent à l’intérieur du verrou — et le push l’indique sous ses autres informations :
carries: every file in the entity's directory, because its source "./charts/{{ .values.flavour }}" is a template and the directory it names is decided by each Release that uses itCe qui n’est pas nommé ne voyage pas, et c’est un consommateur qui s’en aperçoit. Un fichier dont l’entité dépend sans le nommer via l’un des champs ci-dessus n’est pas dans la publication, et le build d’un consommateur échoue en nommant le chemin manquant à l’intérieur de son emplacement de cache — pas votre push. Nommez chaque fichier dont l’entité a besoin via l’un de ces champs.
Chaque fichier publié est nommé dans le manifeste de l’artefact ; un client OCI générique tel que oras l’écrit donc dans un fichier de ce nom : entity.yaml pour une entité publiée sous la forme de son document, entity.tar.gz pour une entité publiée avec ses fichiers, et pour un Plugin entity.yaml pour l’entité à côté de entity.wasm pour son exécutable. Le nom découle du type de média, et non du fichier à partir duquel vous publiez ; le même contenu publié à partir d’un fichier renommé publie donc le même artefact. Catalogue et registre §6 liste chaque forme publiée et le fichier sous lequel chacune arrive.
Une URL source: distante sur une Recipe (une référence de chart OCI, une URL de chart ou de fragment HTTPS, un module Git) est conservée telle quelle dans le YAML publié ; elle n’est ni récupérée ni intégrée à l’artefact. Les consommateurs résolvent et épinglent les sources distantes de manière indépendante, au moment de leur propre pull. Cela maintient la distribution des entités de catalogue et la résolution des artefacts sources comme des préoccupations distinctes.
Un Aggregate est publié sous la forme de son propre document unique : un sous-aggregate qu’il référence dans aggregates: n’est pas empaqueté dans l’artefact. Chaque sous-aggregate est un Aggregate publié séparément que les consommateurs résolvent et épinglent de manière indépendante au moment du pull, par identité — le même principe de séparation de la distribution que celui qui s’applique aux sources distantes.
Une entité par répertoire
Une archive contient le fichier de l’entité parmi les fichiers qu’elle nomme ; l’entité doit donc être retrouvée à la sortie. Un consommateur la trouve grâce au préambule qu’elle porte : le document en tête du bundle dont le kind: est un type d’entité publiable est l’entité. Le fichier dans lequel elle est écrite peut porter n’importe quel nom — recipe.yaml est la convention du catalogue, et non une exigence — et un fragment compose, un template de chart ou un manifeste Kubernetes placé à côté de l’entité n’est pas pris pour elle, car ceux-ci déclarent autre chose ou aucun type. Les documents d’entité plus bas, à l’intérieur d’une arborescence source/, sont du contenu que l’entité livre et non l’entité elle-même, et ne sont jamais pris en compte.
Un push refuse une entité qui partage son répertoire avec une autre entité. Chaque type dispose de son propre répertoire, sauf Aggregate, Release et Manifest, que la racine d’un workspace contient côte à côte. Pour tout autre type, un push vérifie, avant de faire quoi que ce soit d’autre avec l’entité — avant l’étape d’épinglage, la politique de signature et le bundle —, qu’aucun autre document d’entité ne se trouve dans le même répertoire, et refuse dans le cas contraire, en nommant chaque entité qui gêne, qu’il ait été demandé ou non au push d’épingler. aggrega pin refuse le même répertoire dans les mêmes termes ; l’arrêt est An entity shares its directory with another entity (Une entité partage son répertoire avec une autre entité). Un document d’aucun type d’entité à côté de l’entité — un fichier de chart, un fragment compose, un README — ne gêne pas, pas plus que quoi que ce soit dans un sous-répertoire. Chaque document à côté de l’entité n’est lu que depuis l’intérieur du workspace ou, pour une entité que vous nommez en dehors de celui-ci, depuis l’intérieur du répertoire propre de l’entité ; un document qui est un lien menant vers l’extérieur arrête donc le push en nommant le lien, sans le lire, comme l’expose la frontière du workspace.
La règle est ce qui garantit qu’un entity.lock appartient à une seule entité : le nom de fichier du verrou est le même pour chaque entité, de sorte que deux entités écrites dans un même répertoire partageraient l’unique verrou qu’il peut contenir. Elle n’est évaluée que lorsque quelque chose est produit à partir du répertoire ; un répertoire contenant plusieurs entités se charge, passe le lint et se construit donc toujours.
Le nom du répertoire n’est pas évalué. Une entité seule dans son répertoire est publiée à sa metadata.version, où que se trouve ce répertoire ; <name>/<version>/, la disposition que suit le catalogue de la bibliothèque standard, est une convention. Un artefact qu’un autre client a publié depuis un répertoire contenant deux entités est tout de même lu en toute sécurité : un pull de celui-ci s’arrête en nommant les deux documents plutôt que de répondre avec l’un d’eux, comme le catalogue errors/fatal-halts.md.
Lire l’entité avant son empaquetage
Un push lit un Component, une Feature, une Recipe ou une FeatureRecipe comme un build le lit, et refuse ce que cette lecture refuse — pour la même raison, sous le même code court, avant que le bundle ne soit construit et avant que le registre de destination ne soit contacté. Ainsi, un document qui ne respecte pas le schéma de son type, un chemin qui nomme un contenu hors du répertoire propre de l’entité, et un schéma qu’un Component ou une Feature importe avec $import: et qui est absent ou inutilisable sont refusés à la publication au lieu d’être publiés. Chacun d’eux est une entité que le premier build de ses consommateurs refuserait ; un chemin qui sort du répertoire nomme aussi un fichier qui ne voyagerait pas avec l’entité, car chaque fichier que transporte une publication est pris dans le répertoire propre de l’entité — voir A path names content outside the entity’s own directory (Un chemin nomme un contenu situé hors du répertoire propre de l’entité).
Une Recipe ou une FeatureRecipe est lue de cette manière lorsque ses épingles sont comparées, ce que décrit la section suivante ; la lecture a donc lieu qu’il soit demandé ou non au push d’épingler, et que l’entité ait ou non quelque chose à épingler. Chacun des quatre types est aussi lu de cette manière juste avant que son bundle ne soit construit, car c’est cette lecture qui indique quels fichiers il nomme. Un Aggregate et une bibliothèque ne nomment aucun fichier et ne sont pas lus de cette manière. Un Plugin ne nomme aucun fichier non plus, et il est lu par rapport au schéma de son type avant son .wasm, comme le décrit Publier un Plugin.
Publier un Plugin
Un Plugin est publié avec son .wasm, nommé par --plugin, et un push évalue les deux avant qu’aucun octet ne soit publié ou que le registre ne soit contacté. --dry-run les évalue exactement comme le fait une publication.
L’entité est d’abord lue par rapport au schéma de son type, comme la lit un chargement de catalogue, avant que le .wasm ne soit lu. Ainsi, une metadata.version qui n’est pas une version sémantique — un simple commit tel que 415148e — est refusée selon la condition propre du schéma, en nommant le champ, tout comme tout autre écart par rapport au schéma, tel qu’une spec.abiVersion manquante. Ce qui compte ici comme version sémantique est le motif propre du schéma pour metadata.version ; le push n’ajoute aucune règle qui lui soit propre.
Ensuite, le .wasm est chargé et confronté à l’entité. Ce qu’il déclare offrir doit concorder avec ce que l’entité affirme, l’ensemble de commandes et les fonctions hôtes que l’entité enregistre doivent lui correspondre, et la version qu’il déclare pour son propre build doit être égale à metadata.version — voir A Plugin entity’s recorded version does not match the plugin (La version enregistrée d’une entité Plugin ne correspond pas au plugin).
Un .wasm construit à partir d’un arbre de travail comportant des modifications non commitées est refusé. Un tel build porte la marque -dirty à la fin de la version qu’il déclare — 1.0.0-dirty, 1.0.0-3-g1a2b3c4-dirty. C’est une version sémantique valide, mais elle nomme un commit qui ne contient pas ce qui a été construit ; personne ne pourrait donc reconstruire ce qui a été publié à partir de la version sous laquelle il a été publié. Le push le refuse, en nommant la version et la réparation : construisez le plugin à partir d’un checkout propre du commit que nomme le tag de la version publiée, afin qu’il déclare la version publiée elle-même — et, pour publier la modification, commitez-la avec la metadata.version de l’entité définie sur la nouvelle version et appliquez d’abord le tag à ce commit — plutôt que de copier dans l’entité la version que déclare une reconstruction. Une version de développement construite à partir d’un commit, telle que 1.0.0-3-g1a2b3c4, et une préversion telle que 1.0.0-rc.1 sont toutes deux publiées. Le refus est A plugin was built from a working tree with uncommitted changes (Un plugin a été construit à partir d’un arbre de travail comportant des modifications non commitées).
Épingler avant de publier
Une Recipe ou FeatureRecipe porte les pins des entrées qu’elle lit — une source: distante écrite en entier, un fichier qu’une entrée artifacts importe, les fichiers d’une source: à côté d’elle — dans l’entity.lock à côté d’elle, et un push publie ce fichier avec l’entité. L’épinglage est une étape que vous exécutez avant de publier, aggrega pin, puis vous commitez le lock qu’elle écrit.
Un push refuse une entité dont le lock n’enregistre pas ces pins. Avant de construire le bundle, un push détermine ce que l’étape d’épinglage enregistrerait pour l’entité et le compare à l’entity.lock à côté d’elle. Lorsqu’un pin manque, ou que le lock en contient un auquel une entrée ne correspond plus, le push s’arrête avant qu’une archive soit construite ou qu’un registry soit contacté. Le refus nomme l’entité et chacune de ces entrées — chacune une remote source, un imported file ou un local source file — et ce qu’il faut exécuter : aggrega pin sur l’entité, --pin-sources sur le push que vous venez d’exécuter, ou pin_sources_at_push pour chaque push du workspace. C’est le même refus qu’un pull émet sur le même lock, An entity reads an input the lock beside it records no pin for (Une entité lit une entrée pour laquelle le lock à côté d’elle n’enregistre aucun pin), avec les remèdes propres à un push. Ainsi, une Recipe ou FeatureRecipe qu’un push publie porte, dans son bundle, un lock qui enregistre chaque pin que l’étape aurait enregistré au moment de sa publication.
Deux types d’entités n’ont rien à épingler et sont publiés tels quels : une entité qui ne lit aucune source distante, n’importe aucun fichier et ne nomme aucune source locale, et une Recipe dont les coordonnées de source distante sont remplies à partir d’un template. Cette source ne nomme un artefact qu’une fois qu’une Release remplit le template, donc son pin appartient au lockfile de chaque Release, et un push n’en demande pas à côté de l’entité. Un Component, une Feature, une bibliothèque, un Aggregate ou un Plugin ne lit rien de ce que le lock enregistre et n’est jamais refusé ici.
Comparer le pin d’une source distante signifie récupérer la source, comme le fait aggrega pin, car un pin qui ne correspond plus n’est visible que par rapport à ce que la source sert maintenant. Un push sur une entité ayant une telle source atteint donc l’hôte de la source avant d’atteindre le registry. La comparaison lit une Recipe ou FeatureRecipe comme le fait l’étape d’épinglage, via le catalogue, de sorte qu’une entité que le catalogue refuse de lire — un document qui échoue au schéma de son type, par exemple — est refusée ici avec la raison propre au catalogue.
Lorsqu’aucun workspace n’a été trouvé ni désigné, un push qui récupérerait une source distante pour la comparaison est refusé avant de la récupérer, comme l’est aggrega pin. La comparaison récupère chaque source distante que l’entité écrit en entier dans le cache d’artefacts, exactement comme le fait l’étape d’épinglage, et un cache écrit dans un dossier à partir duquel aucun workspace n’a été trouvé ferait de ce dossier un workspace. Ainsi, lorsque rien ne désigne une racine et que rien n’en ancre une — depuis le dossier où vous exécutez le push ou, pour une entité désignée par un chemin absolu, depuis le dossier de l’entité elle-même —, un push d’une Recipe ou FeatureRecipe ayant une telle source s’arrête avant que la source soit récupérée, dry run et --pin-sources compris, et nomme la source, le dossier et les deux solutions : désignez votre workspace avec --workspace-root ou AGGREGA_WORKSPACE_ROOT, ou donnez à ce dossier un .aggrega-config.yaml contenant un bloc workspace:. La comparaison ne récupère rien pour les deux types d’entités ci-dessus, ni pour une entité dont la source est locale, de sorte que chacune d’elles est comparée à son lock et publiée là comme ailleurs ; et tout autre type n’est soumis à aucun lock et n’est pas refusé pour cette raison. Configuration liste les autres commandes concernées.
aggrega push --pin-sources exécute cette même étape pour vous, en premier. L’étape s’exécute avant la construction du bundle, de sorte que le lock qu’elle écrit se trouve dans l’artefact publié et que le digest publié le couvre ; et elle s’exécute avant tout autre refus qui juge l’entité, de sorte que ce qui est jugé est l’entité épinglée. Seule la règle de répertoire ci-dessus passe avant, car l’étape écrit l’unique lock que contient le répertoire. Elle écrit les mêmes octets que aggrega pin, de sorte que le refus ci-dessus ne se déclenche jamais lors de cette exécution : le lock que l’étape vient d’écrire enregistre exactement ce à quoi le refus comparerait. La clé de workspace pin_sources_at_push en fait le comportement par défaut de chaque push, et --pin-sources=false saute l’étape pour une exécution, ce qui rétablit le refus. L’étape écrit à côté de l’entité, ce qui nécessite un emplacement accessible en écriture — et un push en a toujours un, puisqu’il publie le document que vous désignez.
--dry-run répond comme le ferait la publication. Sans --pin-sources, il refuse une entité non épinglée exactement comme le fait la publication, de sorte qu’un dry run qui rapporte un bundle est un dry run que ce refus laisserait passer. Avec --pin-sources, l’étape épingle en dry run : elle affiche le lock qu’elle écrirait et n’écrit rien, et les informations du bundle qui suivent décrivent le répertoire tel qu’il est, sans ce lock — le digest est donc celui d’une publication sans lui et, là où le lock serait nouveau, il en va de même de la taille et, pour une entité qui ne nomme rien d’autre, du media type. Le refus ne se déclenche pas, car la publication aurait d’abord épinglé.
Bonne pratique : une modification d’une version déjà publiée va dans une nouvelle version, puis dans un pin. Copiez l’entité dans un nouveau répertoire de version, effectuez-y la modification, épinglez-la et publiez celle-ci. La moitié de cela que le produit impose est la section suivante : publier un contenu différent sous une version déjà publiée est refusé. L’autre moitié — ne pas ré-épingler une version déjà publiée après l’avoir modifiée dans votre propre workspace — vous revient ; rien ne la refuse localement, car ré-épingler est légitime pour une entité que vous n’avez pas publiée.
Registry, tag et adressage par contenu
Le registry cible est --registry <ref> lorsqu’il est fourni, sinon le default_registry du workspace (hub.aggrega.ai par défaut). Le tag est la metadata.version de l’entité, et le chemin du dépôt est dérivé de son type et de son nom, de sorte que l’endroit où arrive une version publiée ne dépend pas du répertoire à partir duquel elle a été publiée.
Un default_registry peut porter un chemin de dépôt, et une publication par son intermédiaire arrive sous ce chemin. Avec default_registry: ghcr.io/acme, le Component core/api-server en version 1.0.0 est publié à ghcr.io/acme/component/core/api-server:1.0.0 — l’endroit d’où un pull passant par le même défaut le récupère, de sorte que la signature attachée ici est celle que ce pull trouve. --registry désigne un hôte, et une publication qu’il dirige arrive sur cet hôte sans chemin. Quelle que soit la manière dont la destination est désignée, l’exigence de signature et la configuration de signature qui s’appliquent sont celles conservées pour son hôte : un chemin ne sélectionne jamais une politique différente. L’écriture d’un chemin est décrite dans comment s’écrit un hôte de registry.
Le manifest nomme le digest des octets publiés, et le lockfile enregistre le digest de ce qu’ils contiennent. Le manifest OCI qu’écrit un push nomme le digest du document ou de l’archive publiés, et aggrega pull refuse un téléchargement qui ne lui correspond pas, de sorte que des octets modifiés entre la publication et le pull sont détectés. Le lockfile qu’écrit un pull enregistre l’entité par un digest différent : le digest de son contenu — le chemin et les octets de chaque fichier, et rien sur la façon dont l’archive a été compressée ni sur les bits de permission de ses fichiers. C’est le digest qu’un pull dans le propre workspace de l’auteur enregistre pour la même entité dans son répertoire de catalogue, de sorte qu’un auteur et chaque consommateur d’une publication enregistrent la même valeur, et qu’un build de part et d’autre refuse un contenu qui ne lui correspond plus. Les deux digests répondent à des questions différentes : celui du manifest vérifie le téléchargement, et celui du lockfile est l’identité de l’entité.
Publier par-dessus une version existante
Avant tout envoi d’octets, aggrega push détermine ce que le registry cible contient déjà à la référence qu’il s’apprête à écrire et le compare au contenu qu’il a devant lui. Trois résultats :
- Rien n’y est encore publié — le push se poursuit et publie normalement.
- Le même contenu — rien n’est envoyé, et la commande signale la version comme déjà publiée, de sorte qu’un push répété ou relancé n’est pas une erreur. Ce qu’un push précédent a laissé non attaché — la signature ou la date de publication — est attaché maintenant, comme le décrit Compléter une publication laissée partielle par un push précédent.
- Un contenu différent — le push s’arrête, en nommant le digest déjà publié et celui qu’il aurait écrit. Aucun flag ne permet de passer outre.
Une version déjà publiée continue donc de désigner les octets publiés sous elle. Un contenu modifié est publié sous une nouvelle metadata.version ; aggrega lint --pre-publish répond à la question suivante — de combien cette version doit avancer — en classant la modification par rapport à la version publiée précédemment.
--dry-run affiche le digest qu’un push écrirait, à côté de la référence à laquelle il l’écrirait :
aggrega push (dry-run): <reference>:<tag> (<digest>)C’est le digest que le push lui-même compare à ce qui est déjà publié, calculé de la même manière à partir du seul contenu, et son affichage ne contacte aucun registry. Le contenu que vous avez devant vous peut ainsi être confronté au digest sous lequel une version a été publiée avant tout push : là où ils diffèrent pour une version publiée, le push serait refusé. Avec --pin-sources, c’est le digest du répertoire tel qu’il est, comme le décrit Épingler avant de publier.
Compléter une publication laissée partielle par un push précédent
Un push écrit d’abord le contenu et attache la signature et la date de publication ensuite, de sorte qu’un push qui échoue sur l’un de ces attachements — après ses nouvelles tentatives — laisse le contenu publié sans lui et se termine avec un code non nul en nommant ce qu’il n’a pas pu attacher. Relancer le même push complète cette publication. Il trouve le contenu déjà publié, affiche la ligne Already published:, n’envoie rien et attache ce qui manque encore à la version, chacun sur la ligne qu’une première publication affiche pour lui :
- La signature, là où ce push signe. Elle est attachée lorsque la version ne porte aucune signature qui compte comme celle de cette publication. Lorsque votre configuration épingle une politique de confiance pour l’hôte de la destination — une
public_keyou destrusted_identities, ou pourhub.aggrega.aila baseline intégrée —, une signature compte lorsqu’elle se vérifie selon cette politique, de sorte qu’une signature que la politique n’admet pas n’est jamais prise pour celle de la publication. Lorsque la politique n’épingle ni l’un ni l’autre, aucune signature ne peut être vérifiée par rapport à elle, de sorte que toute signature portée par la version compte et que le push ne signe qu’une version qui n’en porte aucune ; juger par la vérification attacherait alors une autre signature à chaque exécution. - La date de publication, là où la règle des dates en exige une — lue dans la signature tout juste attachée, ou dans celle déjà comptée — et que la version ne porte aucun referrer published-at. Un push qui ne signe pas doit une date comme une publication non signée, quelles que soient les signatures attachées à la version ensuite. La date qu’il indique est l’horloge de ce push : le moment où la publication a été complétée, qui est postérieur au moment où le contenu est arrivé pour la première fois, puisque rien de ce que sert le registry n’enregistre ce moment.
Une publication déjà complète ne reçoit aucun attachement, quel que soit le nombre de répétitions du push. Avant d’attacher quoi que ce soit, le push lit quelles signatures et dates porte la version et crée toute signature qu’il doit. Une question à laquelle il ne peut pas répondre — une liste ou une signature qu’il ne peut pas lire, ou une signature qu’il ne peut pas juger parce que la racine de confiance ne peut pas être obtenue — et une signature qu’il ne peut pas créer se terminent chacune avec un code non nul sans rien attacher, au lieu d’être interprétées comme signifiant que la version n’en porte aucune.
Lorsque le registre fait échouer une écriture
Un push écrit dans le registry par étapes : le contenu — pour un Plugin, l’entité et son .wasm —, puis le manifest qui le nomme, puis le tag de version, puis la signature et la date de publication à côté. Chaque étape d’écriture est retentée lorsqu’elle échoue d’une manière dont une tentative ultérieure peut triompher : le registry répond par une erreur serveur (tout statut 5xx, hormis un 503 accompagné de Retry-After) ou 408 Request Timeout, ou la connexion expire, est réinitialisée ou se termine au milieu d’une réponse. Une étape est tentée au plus trois fois, avec une attente d’une demi-seconde avant la deuxième tentative et d’une seconde avant la troisième.
Un registry qui demande de ralentir est attendu, et ne consomme aucune de ces tentatives. Sur un 429 Too Many Requests, ou un 503 accompagné de Retry-After, chaque requête vers ce registry — une lecture autant qu’une écriture — attend aussi longtemps que le registry l’a demandé puis repart, une étape dont le contenu a été refusé recommençant comme un nouvel envoi, sans nombre fixe de tentatives, jusqu’à ce que le registry n’ait rien répondu d’autre que « ralentissez » pendant cinq minutes. Un registre qui demande de ralentir décrit l’attente et le refus qui y met fin.
Chaque tentative est un nouvel envoi des mêmes octets, jamais un renvoi de la requête qui a échoué. Un registry qui a déjà reçu le corps d’un envoi peut refuser la même requête une seconde fois, et c’est un nouvel envoi qu’il accepte. Un contenu que le registry détient déjà compte comme envoyé, et une étape retentée écrit ce que la première tentative aurait écrit, de sorte qu’une tentative qui a abouti mais dont la réponse a été perdue n’écrit rien deux fois : le manifest conserve son digest, et la version porte une seule signature et une seule date de publication.
Tout autre échec met fin à l’étape immédiatement : un identifiant refusé (401, 403, ou aucun identifiant enregistré pour le registry), toute autre réponse du registry, un registry injoignable, ou un push que vous interrompez. Une étape qui échoue encore après sa dernière tentative fait échouer la commande, et l’erreur nomme l’étape — le contenu, le manifest, le tag, la signature ou la date de publication. Ce que les étapes précédentes ont publié reste publié ; Signature et La date de publication expliquent ce que cela signifie pour la version.
Seules les écritures sont retentées pour ces échecs. La lecture de ce que le registry contient déjà à la version, avant tout envoi, ne l’est pas, même si elle attend, comme toute requête, le temps qu’exige un registry qui demande de ralentir.
Signature
aggrega push peut signer l’artefact lors de sa publication et attacher la signature comme referrer OCI — un bundle Sigstore (compatible cosign) sur le digest immuable du manifest de l’artefact. La signature est un manifest frère, de sorte que signer ne republie ni ne modifie jamais les octets publiés. Le referrer nomme son bundle signature.json, de sorte qu’un client OCI générique qui récupère le referrer par son digest écrit le bundle dans ce fichier.
La signature se fait sign-before-push : le digest du manifest est connu avant la publication, donc aggrega push construit le signataire et signe le digest avant qu’aucun octet n’atteigne le registry. Si le signataire ne peut pas être construit ou si la signature échoue, le push est refusé avant tout envoi — rien n’est publié, de sorte qu’une signature échouée ne laisse jamais de contenu non signé sur le registry. Avant de refuser, un appel de signature qui a échoué de manière transitoire — tout échec pour lequel une écriture dans le registry est retentée, ou l’autorité de certification keyless signalant qu’elle n’a pas pu traiter le jeton d’identité — est retenté, jusqu’à trois tentatives avec les mêmes attentes. Au sein d’un appel de signature keyless, une requête à laquelle l’autorité de certification, le journal de transparence ou l’autorité d’horodatage répond par 429 Too Many Requests ou par une erreur serveur est d’abord renvoyée à ce service, comme le décrit aggrega sign.
La signature est attachée après l’arrivée du contenu, de sorte qu’un attachement échoué laisse bel et bien le contenu publié sans elle. L’attachement est une écriture, retentée comme le décrit Lorsque le registry fait échouer une écriture. S’il échoue encore, la commande se termine avec un code non nul en nommant la signature qu’elle n’a pas pu attacher, et un consommateur dont le registry exige des signatures refuse la version jusqu’à ce qu’une signature soit attachée. Relancer le même push l’attache, comme le décrit Compléter une publication laissée partielle par un push précédent ; aggrega sign en attache une à la version publiée par référence.
Une publication exige une signature lorsque le bloc signing propre au registry de destination définit required: true, ou que le bloc signing de premier niveau le fait pour tous les registries — chacun limité aux types que liste son kinds, lorsqu’il en liste. Une telle publication signe par défaut, et --sign demande explicitement la signature. Il n’existe aucun flag pour pousser un contenu non signé là où une signature est exigée — ce push s’arrête toujours.
Deux modes de signature :
- Keyless (par défaut) — une clé éphémère liée à une identité OIDC par un certificat Fulcio de courte durée, enregistrée dans le journal de transparence Rekor. Fulcio et Rekor utilisent par défaut les instances Sigstore publiques (
https://fulcio.sigstore.dev,https://rekor.sigstore.dev). L’horodatage de confiance keyless provient de l’inclusion dans le journal de transparence de Rekor ; une autorité d’horodatage RFC3161 distincte est facultative — fournissez--timestamp-urlavec un endpoint complet pour en activer une. Dans un terminal interactif, la signature keyless ne nécessite aucun flag : la CLI ouvre un navigateur pour obtenir un jeton d’identité OIDC de courte durée. Sur GitHub Actions, elle n’en nécessite pas non plus : la CLI génère automatiquement le jeton OIDC du workflow à partir de l’endpoint ambiant du runner. Pour les autres usages non interactifs / CI, exportezAGGREGA_IDENTITY_TOKEN(ouSIGSTORE_ID_TOKEN), ou passez--identity-token; sans jeton fourni, sans endpoint ambiant et sans terminal, le push est refusé. Voir environment-variables.md pour le modèle de jetons en CI. - Keyed (
--key) — une clé ECDSA P-256 détenue hors ligne (PEM compatible cosign), la porte de sortie pour les environnements sans fournisseur d’identité OIDC. Aucun fournisseur d’identité, aucune autorité de certification ni aucun journal de transparence n’est contacté.
Les URL des services keyless et le chemin de la clé keyed peuvent aussi être définis dans .aggrega-config.yaml sous un bloc signing: (global et par registry) ; un flag remplace la configuration, et la configuration remplace le défaut public. Le jeton d’identité OIDC n’est jamais un champ de configuration (c’est un secret de courte durée), et la clé privée n’est jamais inline dans la configuration — seulement un chemin vers elle.
La date de publication
L’heure de création du manifest est figée, de sorte que le digest d’un manifest ne dépend que de ce qui est publié et jamais du moment. La date de publication d’une version voyage plutôt à côté d’elle, et sa provenance dépend de la signature :
- Une signature keyless la porte déjà. Son entrée dans le journal de transparence enregistre le moment où le journal a intégré la signature, et la promesse signée du journal atteste ce moment.
aggrega pushn’écrit rien de plus. - Une signature keyed, ou l’absence de signature, ne porte aucune heure. Ainsi, une fois l’entité et l’éventuelle signature arrivées,
aggrega pushattache au manifest un petit referrer published-at — nommépublished-at.jsonpour un client OCI générique — contenant un horodatage RFC 3339 en UTC à la seconde près, lu sur l’horloge de la machine qui publie. Il n’est pas signé : c’est la déclaration de l’éditeur, et un lecteur l’enregistre comme telle. La lignePublication date attached:le signale.
Comme une signature, le referrer published-at est un manifest frère qui pointe vers le manifest publié, de sorte qu’il ne déplace aucun digest et ne change aucun tag, et la vérification lors de la publication par-dessus une version existante n’en est pas affectée. Un push répété du même contenu n’attache une date qu’à une version qui n’en porte aucune, en indiquant sa propre horloge — voir Compléter une publication laissée partielle par un push précédent. La date est lue sur l’horloge une seule fois, avant la première tentative d’attachement, de sorte qu’un attachement retenté — voir Lorsque le registry fait échouer une écriture — indique la même date. Un push qui a publié son contenu mais n’a pas pu attacher la date après ces tentatives se termine avec un code non nul et nomme ce qui n’a pas été attaché. aggrega registry update enregistre la date de chaque version ainsi que celle des deux sources dont elle provient.
Hors ligne
Publier est un aller-retour réseau et n’a aucune forme qui ne le soit pas, donc en mode hors ligne — la clé de premier niveau offline dans un fichier de configuration, AGGREGA_OFFLINE ou --offline — aggrega push refuse avant de lire votre entité. Le refus indique laquelle de ces trois sources a défini le mode, ce dont un lecteur a besoin lorsque c’est la configuration commitée d’un projet qui l’a activé plutôt que quelque chose qu’il a saisi.
--dry-run est l’exception, et c’en est une en raison de ce qu’il fait : il calcule le bundle, affiche la référence qu’il publierait et le digest que produirait cette publication, et ne contacte jamais le registry. Cela en fait la forme de publication sûre hors ligne plutôt qu’un conflit avec le mode, et il continue de fonctionner sous celui-ci — avec une réserve. Pour une Recipe ou FeatureRecipe dont la source: distante est écrite en entier, cette source est récupérée pour comparer son pin, et en mode hors ligne cette récupération est refusée avec son propre message, de sorte qu’un dry run sur une telle entité s’arrête là plutôt que de rapporter un bundle dont il ne peut se porter garant.
Pour publier le temps d’une exécution depuis un workspace dont la configuration est hors ligne, passez --offline=false.
Variables d’environnement
Les entrées de signature et le registry de destination peuvent être fournis par l’environnement, en remplaçant .aggrega-config.yaml, tandis qu’un flag l’emporte toujours :
AGGREGA_IDENTITY_TOKEN— le jeton d’identité OIDC keyless (l’équivalent en variable d’environnement de--identity-token).SIGSTORE_ID_TOKENest accepté comme alias d’interopérabilité de l’écosystème sigstore, classé aprèsAGGREGA_IDENTITY_TOKENet l’endpoint ambiant de GitHub Actions. Le jeton n’est jamais un champ de configuration.AGGREGA_SIGNING_FULCIO_URL,AGGREGA_SIGNING_REKOR_URL,AGGREGA_SIGNING_TIMESTAMP_URL— les URL des services keyless.AGGREGA_SIGNING_KEY_PATH— un chemin pointant vers un PEM de clé keyed (jamais le matériel de clé).AGGREGA_DEFAULT_REGISTRY— le registry de destination lorsque--registryest omis.
L’ordre de priorité est flag > environnement > configuration > défaut. Voir environment-variables.md pour la liste complète et le modèle de priorité.
Authentification
aggrega push lit les identifiants de registry comme aggrega pull — depuis la configuration des identifiants Docker et les credential helpers qu’elle nomme. Exécutez aggrega login <registry>, qui ne nécessite aucun autre outil, ou docker login <registry> avant de pousser vers un registry privé. Voir aggrega-pull.md pour savoir où cette configuration est lue.
Voir aussi
- ./aggrega-sign.md — signe après coup un artefact déjà publié (l’équivalent post-publication de
--sign). - ./aggrega-lint.md — le contrôle de publication (
--pre-publish) qui devrait précéder un push. - ./aggrega-pull.md — le côté consommateur, qui résout et épingle ce que
pushpublie. - ./aggrega-serve.md — le daemon propose cette même publication via
aggrega/publishEntity, de sorte qu’un éditeur peut l’exécuter sans quitter la session ; elle ne s’exécute que lorsqu’une requête la nomme, et répond avec la référence, le digest publié — en dry run, le digest qu’affiche--dry-run—, le point atteint par l’appel, et les entrées au sujet desquelles cette commande avertit, souswindowsUnusableEntries. - ./aggrega-mcp.md — la même capacité sous la forme de l’outil
publish-entity, qu’un assistant peut appeler et qui répond avec ces entrées souswindows_unusable_entries. Lisez ce que cette page dit sur son autorisation avant de l’autoriser. - ../../architecture/13-catalog-and-registry.md — le modèle de catalogue, de registry et de media types OCI.
Synopsis
aggrega push <entity-path> [flags]Description
Publish a single catalog entity to an OCI registry, where other workspacesresolve it with "aggrega pull".
The entity is read from the path given, bundled for transport, and pushed to<registry>/<kind>/<metadata.name>:<metadata.version>, the repository pathlowercased; a Recipe or FeatureRecipe carries its spec.capability, and a Pluginits metadata.pluginType, as a segment between <kind> and <metadata.name>. Thetag is the entity's own metadata.version. Run "aggrega push --list-kinds" forthe kinds this binary publishes, one per line and nothing else, so a script canread it directly. Release and Manifest are deployment-side inputs rather thancatalog artifacts and are refused.
Every kind has a directory of its own except Aggregate, Release and Manifest: anentity of any other kind is refused when another entity sits in its directory,before anything is pinned or bundled, and the refusal names the entity in the way.The directory's name is not judged.
A Component, Feature, Recipe or FeatureRecipe is read the way a build reads itbefore it is bundled, and one that read refuses is refused here for the samereason: a document that fails its kind's schema, a path naming content outsidethe entity's own directory, which would not travel with the entity, or a schemaa Component or Feature imports that cannot be read or used.
A Plugin is read against its kind's schema too, before its .wasm is read, so ametadata.version that is not a semantic version is refused. Its .wasm must thenagree with the entity on what the plugin offers and on its version, and a .wasmwhose version says it was built from a working tree with uncommitted changes —the -dirty mark a build adds — is refused. A version disagreement and a buildfrom uncommitted changes are both cleared by building the plugin from a cleancheckout of the commit its release tag names, never by copying the version itreports into the entity. A development version such as 1.0.0-3-g1a2b3c4, builtfrom a commit, and a prerelease such as 1.0.0-rc.1 publish.
What is published is the entity document and the files the entity itself namesbeside it — a Recipe's or FeatureRecipe's local source, each file an $import:names, the entity.lock beside it, and each schema file a Component or Featureimports — and nothing else in its directory. An entity that names nothingpublishes as its document, unchanged; one that names a file publishes as agzipped archive of the document and those files. A directory it names travelswith every file under it that the ignore rules recorded in its entity.lock keep:the rules the plugin serving its capability declared, and the author's own.aggregaignore beside it, composed when the entity was pinned. A symbolic linkamong those files is refused rather than followed. A local source written as atemplate names no one directory until a Release fills it in, so an entity withone carries every such file in its own directory, and push says so.
Push warns about each file an archive carries whose path holds a part Windowscannot hold as written: a name Windows reserves for a device — CON, PRN, AUX,NUL, COM1 or LPT1, say, in any letter case and whatever extension follows — or apart ending in a full stop or a space. On Windows, aggrega refuses to unpacksuch a file, so a Windows workspace cannot use the version. The warning iswritten to standard error on every platform, one line per file, the entitydocument's own file name judged with the rest, and it refuses nothing: the push,or its dry run, goes ahead or stops exactly as it would without it. An entitythat names nothing publishes as its document alone and is never warned about.
Each file travels with mode 0644, whatever its permission bits — the executebit included — in the checkout it is published from. The OCI manifest names thedigest of the published bytes, so "aggrega pull" refuses a download that doesnot match it. The lockfile a pull writes records the entity by the digest of itscontent — each file's path and its bytes — which is the digest a pull in theauthor's own workspace records for the same entity in its catalog directory, soa build on either side refuses content that no longer matches.
Push signs before it publishes: where signing applies, the signature is madeover the manifest digest before any bytes reach the registry, so a failedsigning refuses the push rather than leaving unsigned content published.
The manifest's creation time is pinned, so the digest depends only on what ispublished and never on when. Push states when it published beside the manifestinstead, as a small published-at attachment carrying this machine's clock, inUTC to the second — unless the signature it attached already carries a time atransparency log attests, as a keyless signature does. So a keyed or unsignedpublication writes one, and a keyless one does not. The attachment moves nodigest and changes no tag. "aggrega registry update" records the date, withwhich of the two it came from.
Push refuses to replace content already published at the same version:publish changed content under a new version instead.
A Recipe or FeatureRecipe carries the pins for its own inputs in the entity.lockbeside it, and pinning them is a step you run before publishing: aggrega pin.A push that does not run that step refuses an entity whose entity.lock ismissing a pin, or holds one an input no longer matches, and names the step.Pass --pin-sources, or set pin_sources_at_push in the workspace configuration, tohave push run that same step first, so the lock it writes is part of what ispublished; --pin-sources=false skips it for one run.Options
| Option | Par défaut | Description |
|---|---|---|
--dry-run | false | Calcule le bundle et affiche le |
--entity | — | Chemin du YAML de l’entité à publier (ou passez-le comme argument positionnel) |
--fulcio-url | — | URL de l’autorité de certification Fulcio pour la signature sans clé. Si elle est omise, l’instance publique de Fulcio est utilisée. |
--identity-token | — | Jeton d’identité OIDC pour la signature sans clé. Facultatif dans un terminal interactif (un flux dans le navigateur en obtient un) et sur GitHub Actions (le jeton OIDC du workflow est émis automatiquement) ; obligatoire pour les autres usages non interactifs/CI, où il peut à la place être exporté sous la forme AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN. |
--key | — | Chemin d’un PEM de clé privée ECDSA P-256 détenue, pour la signature hors ligne avec clé. S’il est omis, la signature sans clé est utilisée. |
--list-kinds | false | Liste chaque type d’entité pouvant être publié, puis quitte sans rien publier. La sortie est lisible par une machine et sa forme est stable : un type par ligne, dans l’ordre trié, sans rien d’autre. |
--pin-sources | false | Exécute l’étape d’épinglage de l’auteur de l’entité sur l’entité avant de la mettre en bundle, de sorte que l’entity.lock que l’étape écrit à côté d’elle fait partie de ce qui est publié, au lieu de refuser une entité dont le lock n’enregistre pas ses pins. La même étape que aggrega pin, qui écrit les mêmes octets. Elle écrit à côté de l’entité, et ne s’exécute donc que là où l’entité a un emplacement accessible en écriture : un document dans un répertoire à partir duquel il a été lu — ce qu’un push a toujours, puisqu’il publie le document d’entité que vous désignez. Remplace pin_sources_at_push du workspace dans les deux sens : —pin-sources épingle pour cette exécution et —pin-sources=false non, quoi qu’indique le paramètre |
--plugin | — | Chemin de l’artefact .wasm local pour une entité Plugin. Obligatoire lors de la publication d’un Plugin : la publication pousse l’artefact .wasm, calcule son digest de contenu et pousse l’entité. |
--registry | — | Hôte du registre de destination (remplace le default_registry du workspace) |
--rekor-url | — | URL du journal de transparence Rekor pour la signature sans clé. Si elle est omise, l’instance publique de Rekor est utilisée. |
--sign | false | Signe l’artefact publié et attache la signature comme referrer OCI. S’il est omis, la signature suit la politique du registry de destination. |
--timestamp-url | — | URL facultative de l’autorité d’horodatage RFC3161 pour la signature sans clé. |