Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

aggrega deprecate

Attacher un marqueur de dépréciation signé à un artefact déjà publié

Synopsis

aggrega deprecate <reference> [flags]

Description

Deprecate amends an already-published artifact by attaching a deprecation marker to it as an OCI referrer, then signing that marker. It does not re-push, re-tag, or otherwise mutate the published bytes — the artifact is immutable; the marker is a sibling manifest pointing back at it, so a marker can be attached retroactively. The marker records a severity (warning, error, or retracted), a reason, an optional replacement reference, and the timestamp it was issued. Run it three ways: pass the content as flags; omit the content flags at an interactive terminal to be prompted for severity, reason, and replacement; or pass --from <file> to attach one marker per entry from a batch file, whose entries carry their own content, so a content flag passed beside --from is refused rather than ignored. The marker itself is signed the same way artifacts are: its manifest digest is signed and the signature is attached as a referrer of the marker, so the marker is verifiable the same way artifact signatures are. With --key the signature is produced offline from a held ECDSA P-256 key; without --key the keyless flow is used, which requires a live identity provider, Fulcio, and Rekor. Every marker of one --from batch is signed with one credential: where the configuration names a held key (signing.key_path) for one entry's registry and none for another's, or two different keys, no marker is attached and the command says to run one batch per credential.

Options

OptionPar défautDescription
--from—Fichier de lot (YAML, ou JSON en tant que sous-ensemble) dont la liste de premier niveau attache un marqueur par entrée. Chaque entrée contient reference, severity et reason, ainsi que replacement et message facultatifs. Mutuellement exclusif avec une référence positionnelle et avec —severity, —reason, —replacement et —message.
--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.
--message—Message facultatif conservé pour l’audit et pour le diagnostic enregistré au moment du build ; vaut par défaut —reason s’il n’est pas défini. Refusé à côté de —from, dont les entrées portent le leur.
--reason—Raison lisible par un humain de la dépréciation — pourquoi il est déprécié et quoi faire à la place. Obligatoire avec une référence positionnelle sauf si une invite interactive la fournit ; refusée à côté de —from, dont les entrées portent la leur.
--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.
--replacement—Référence facultative de l’artefact qui remplace celui qui est déprécié. Refusée à côté de —from, dont les entrées portent la leur.
--severity—Sévérité de la dépréciation : l’une de warning, error, retracted. Obligatoire avec une référence positionnelle sauf si une invite interactive la fournit ; refusée à côté de —from, dont les entrées portent la leur.
--timestamp-url—URL facultative de l’autorité d’horodatage RFC3161 pour la signature sans clé.

D’où viennent les points de terminaison de signature

Les URL Fulcio et Rekor de la signature sans clé et le chemin de clé de la signature avec clé peuvent aussi provenir du bloc signing: de .aggrega-config.yaml (global et par registre, où une valeur définie pour le registre de l’artefact l’emporte sur la valeur globale, champ par champ) ; un flag remplace la configuration, et la configuration remplace la valeur par défaut public-good. Les instances public-good nommées dans le tableau des flags ne sont donc utilisées que là où ni un flag ni la configuration de votre workspace ne nomme un point de terminaison. Le marqueur est signé exactement comme aggrega sign signe un artefact.

Lorsque le registre fait échouer une écriture

Déprécier un artefact écrit deux fois dans le registre : le marqueur, attaché comme référent de l’artefact, puis la signature du marqueur, attachée comme référent du marqueur. Chaque écriture est retentée lorsque le registre ou le réseau la fait échouer d’une manière dont une tentative ultérieure peut réussir, comme une erreur du serveur, un délai dépassé ou une connexion réinitialisée ; aggrega push liste ces échecs. Une écriture est tentée au plus trois fois, à une demi-seconde puis à une seconde d’intervalle, et chaque tentative est un nouveau téléversement des mêmes octets plutôt qu’un renvoi de la requête qui a échoué. L’horodatage du marqueur est apposé une seule fois, avant la première tentative, de sorte qu’une écriture retentée laisse un seul marqueur et une seule signature, et non deux.

La signature du marqueur, entre les deux écritures, n’est pas retentée dans son ensemble ; au sein d’une 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 envoyée de nouveau à ce service, comme le décrit aggrega sign. Une écriture qui échoue encore après sa dernière tentative, ou une signature qui échoue, arrête la commande et nomme l’étape ; un marqueur déjà attaché à ce moment reste attaché sans sa signature. Avec --from, les entrées attachées avant celle qui a échoué restent attachées.

Un fichier de lot porte le contenu de chaque marqueur

Avec --from, la sévérité, la raison, le remplacement et le message de chaque marqueur proviennent de sa propre entrée dans le fichier de lot. Un --severity, --reason, --replacement ou --message passé à côté de --from est donc refusé plutôt qu’ignoré : la commande nomme chacun de ceux qui ont été passés et s’arrête avant que le fichier de lot ne soit lu, de sorte qu’aucun marqueur n’est attaché. Placez le contenu dans les entrées du fichier, ou dépréciez une seule référence avec ses flags de contenu.

Un lot est signé avec un seul identifiant

Avec --from, chaque marqueur du fichier de lot est signé avec le même identifiant : une seule clé détenue, ou une seule identité sans clé demandée une fois pour tout le fichier. Celui dont une entrée a besoin est déterminé par la configuration du registre de sa référence — un signing.key_path qui s’applique à ce registre sélectionne la clé qu’il nomme, et lorsqu’aucun ne s’applique le marqueur est signé sans clé. Lorsque les entrées nécessiteraient des identifiants différents — la configuration nomme une clé pour un registre et aucune pour un autre, ou deux clés différentes —, aucun marqueur n’est attaché et la commande nomme les registres de chaque côté. Elle le fait avant qu’aucune identité ne soit demandée et avant qu’aucun registre ne soit lu.

Divisez le fichier en un lot par identifiant, ou passez une seule clé avec --key, qui s’applique à chaque entrée quoi que dise la configuration pour chaque registre. Le message est décrit dans References signed together need different signing credentials (Les références signées ensemble nécessitent des identifiants de signature différents).

Le signataire de chaque entrée est également préparé avant que le premier marqueur ne soit attaché, de sorte qu’une clé illisible, ou un jeton d’identité fourni qui ne contient aucun sujet utilisable, arrête le lot sans que rien ne soit attaché.

Ce que fait chaque sévérité

Les trois sévérités forment un ensemble ordonné — warning, puis error, puis retracted — et se répartissent en deux niveaux qui diffèrent par le moment où ils agissent.

warning et error sont des niveaux consultatifs. Un marqueur de l’une ou l’autre sévérité ne change jamais la version vers laquelle une référence se résout. Il est enregistré lorsque vous exécutez aggrega pull, et chaque surface qui lit le lockfile le signale.

Chacune de ces surfaces signale chaque référence dépréciée que le lockfile épingle, quelle que soit la sévérité, en nommant la référence, sa sévérité, son message et le moment où l’enregistrement a été observé :

SurfaceCe qu’elle fait d’un marqueur enregistré
aggrega buildLe signale, et s’arrête si vous avez configuré un arrêt à cette sévérité.
aggrega validate --releaseLe signale. Le verdict est inchangé.
aggrega lint --releaseLe signale. Le verdict est inchangé.
aggrega serveLe publie dans votre éditeur sous forme d’avertissement tant que l’Aggregate est ouvert. Un marqueur nomme une référence ou un plugin plutôt qu’un document de votre espace de travail, il reste donc sur l’Aggregate ; seules les erreurs de mappage propres à un Manifest sont affichées sur le Manifest.
L’outil build natif pour l’IALe signale, et refuse si vous avez configuré un arrêt à cette sévérité.
Les outils describe et validate natifs pour l’IALe signalent avec leur propre sortie.

Le fait qu’un marqueur arrête aussi un build est un paramètre distinct : build.halt_on_deprecated_severity n’est pas défini par défaut, si bien que rien ne s’arrête, et le définir sur une sévérité provoque un arrêt à cette sévérité et au-delà. Il régit le build — aggrega build et l’outil de build natif pour l’IA, qui est la même opération — et rien d’autre : les surfaces de signalement nomment le marqueur et continuent dans tous les cas. Relever le seuil ne réduit jamais ce qui vous est signalé, sur aucune surface — vous recevez toujours l’avis pour tout ce qui se situe en dessous, et pour tout ce que l’arrêt ne couvre pas.

Certains plugins sont enregistrés ailleurs, et leurs marqueurs proviennent de là. Un attachement plugins.linter, et un attachement plugins.governance dans un rôle ir-verdict ou render-verdict, ne façonnent rien de la sortie rendue ; ils sont donc épinglés dans plugins-trust.yaml à côté du lockfile plutôt que dans le lockfile lui-même. Chaque enregistrement qui s’y trouve contient le marqueur découvert pour le plugin qu’il nomme, à côté de son identité, et aggrega pull en enregistre un de la même manière qu’il enregistre un marqueur sur une ligne du lockfile.

aggrega build, aggrega lint --release et aggrega validate --release lisent les deux enregistrements, de sorte qu’un plugin déprécié y est nommé tout comme une référence dépréciée, et build.halt_on_deprecated_severity régit les deux de la même façon. Deux différences méritent d’être connues. L’avis pour un tel plugin n’indique pas quand l’enregistrement a été observé — ce fichier ne contient aucun horodatage, ce qui lui permet d’être reproduit octet pour octet —, il nomme donc plutôt l’origine de l’information et la commande qui l’actualise. Et une entrée qui s’y trouve n’est jamais réécrite par un pull ordinaire : un marqueur nouvellement publié est ajouté à l’enregistrement que le plugin possède déjà, tandis que l’identité à laquelle il est tenu reste inchangée jusqu’à ce que vous demandiez à la changer avec aggrega pull --upgrade.

retracted est le niveau de retrait, et il agit aussi plus tôt. Une version enregistrée comme retirée est écartée de l’examen lorsque aggrega pull choisit une version pour une référence qui n’en nommait pas. Si une autre version publiée satisfait la référence, cette version est retenue et le pull le signale, en nommant la version qu’il a ignorée, la raison enregistrée contre elle et la version qu’il a retenue à la place. Si aucune version publiée ne reste pour satisfaire la référence, le pull s’arrête et indique que tous les candidats ont été retirés — il ne signale pas l’entité comme manquante, et ne se rabat jamais en silence.

Nommer explicitement une version prime sur le retrait

Une référence qui nomme une version exacte se résout toujours vers cette version, qu’elle ait été retirée ou non. Nommer la version est la dérogation ; il n’existe donc aucun paramètre distinct pour désactiver l’exclusion — et une version épinglée par un aggrega pull précédent continue de se résoudre exactement pour la même raison.

Le pull le dit clairement lorsque la version que vous avez nommée a été retirée, de sorte que le build qui s’y était déjà engagé continue de fonctionner tout en vous permettant de voir pourquoi vous pourriez vouloir changer.

Les enregistrements de retrait sont un instantané, pas une réponse en direct

Un artefact publié est immuable, mais un retrait ne l’est pas : une version peut être retirée après votre dernière vérification. L’exclusion lit ce que votre workspace a enregistré la dernière fois qu’il a construit son index local du registre ; elle vous protège donc de la sélection d’une version connue comme retirée. Elle ne peut pas vous dire qu’une version n’est pas retirée en ce moment même.

Chaque signalement d’un marqueur enregistré antérieurement indique quand cet enregistrement a été observé, de sorte qu’un enregistrement périmé se distingue d’un enregistrement récent, et chacun nomme la commande qui l’actualise. Deux enregistrements sont conservés et s’actualisent séparément : l’exclusion de versions et aggrega inspect lisent votre index local du registre, qu’actualise aggrega registry update, tandis que aggrega build lit le marqueur enregistré dans le lockfile, qu’actualise aggrega pull. Ce que aggrega pull affiche pendant sa recherche ne porte aucun moment de ce type — il signale ce qu’il vient de trouver à cet instant.

Pour la même raison, l’absence de retrait ne prouve pas qu’il n’en existe aucun — seulement qu’aucun n’avait été enregistré lors de votre dernière actualisation.

Où vous êtes informé

La commande qui vous informe d’un retrait découle de l’enregistrement qu’elle lit. Le tableau plus haut couvre le marqueur enregistré dans votre lockfile — ce que cette Release a épinglé. Celui-ci couvre l’index local du registre — ce qu’un registre a publié — qui est l’enregistrement que lit l’exclusion de versions.

CommandeCe qu’elle vous dit d’un retrait enregistré
aggrega registry updateNomme chaque marqueur qu’elle rencontre en parcourant le registre : le dépôt, la version sur laquelle il a été enregistré, la sévérité et si le marqueur a été enregistré. Chaque registre indique ensuite combien de marqueurs son index contient désormais.
aggrega searchIndique la version qu’une résolution prendrait plutôt qu’une version révoquée, et nomme les versions révoquées dans une colonne NOTES. --include-retracted indique à la place la version publiée la plus élevée.
aggrega inspectAffiche la sévérité enregistrée sous l’entité, avec la version sur laquelle elle a été enregistrée, la raison, le remplacement lorsqu’il en est nommé un, et la date d’émission — pour chaque type qu’elle résout par nom.
aggrega pullNomme chaque version ignorée, la raison enregistrée à son encontre et la version prise à la place. Une version que vous avez nommée explicitement est tout de même résolue, et le retrait est annoncé plutôt qu’appliqué.
aggrega plugin addLa même chose : une version qu’elle choisit est filtrée sur chacune des deux voies par lesquelles elle en résout une, et une version que vous nommez sous la forme <name>:<version> est tout de même résolue, le retrait étant annoncé. Lorsque les marqueurs n’ont pas pu être lus, elle le signale et indique que les versions publiées n’ont pas été filtrées.
aggrega buildRien de cet enregistrement. Elle ne lit que votre lockfile et jamais l’index, donc ce qu’elle indique est le marqueur enregistré pour la version que vous avez épinglée.
aggrega serveRien de cet enregistrement. Sa propre résolution ne consulte pas les enregistrements de retrait, donc une version révoquée peut encore y être sélectionnée ; elle publie le marqueur du lockfile vers votre éditeur.

Lisez les deux dernières lignes avec les autres : une commande vous informe d’un retrait uniquement là où elle fait quelque chose sur quoi le retrait a une incidence — choisir une version, ou vous montrer ce qu’un éditeur de paquets a déclaré. Le silence d’une commande qui ne fait ni l’un ni l’autre ne prouve pas que rien n’est enregistré.

Un avis nomme la sévérité que l’éditeur a enregistrée. Un artefact révoqué est signalé comme retracted ; les deux sévérités consultatives sont signalées comme dépréciées, en précisant laquelle des deux. Ainsi, ce que vous relisez correspond à la valeur qui a été rédigée et à la valeur avec laquelle vous configureriez un seuil d’arrêt.

Deux types d’avis sont tenus séparés parce qu’ils signalent des événements différents. Une ligne deprecation: vous apprend quelque chose sur un artefact. Une ligne retraction: vous dit ce que vous n’avez pas obtenu — une version qui a été ignorée, ou un filtrage qui n’a pas pu être effectué. Lorsqu’une commande émet les deux pour le même artefact, ce sont deux faits plutôt qu’une même affirmation faite deux fois.

Quelles résolutions l’exclusion couvre

L’exclusion agit partout où une commande choisit une version pour vous. C’est la règle, et elle détermine si une résolution donnée est couverte.

aggrega pull l’applique partout où elle choisit une version pour une référence qui n’en nommait pas — quoi que nomme la référence : une entité du catalogue, une bibliothèque, un Aggregate publié. Une seule règle les régit toutes, de sorte que la version vers laquelle une référence se résout ne dépend pas du type de référence qui l’a demandée.

aggrega plugin add l’applique sur chaque voie par laquelle elle résout une référence de plugin non épinglée : par rapport aux versions publiées que votre index local du registre contient déjà, et par rapport à la liste de versions en direct qu’elle consulte lorsque cet index ne contient pas le dépôt. Une version retirée est ignorée, et la substitution annoncée, quelle que soit la voie qui l’a résolue.

Le daemon côté éditeur est l’exception. Il résout les références à la demande pendant qu’il sert un éditeur, et cette résolution choisit des versions sans consulter les enregistrements de retrait, de sorte qu’une version enregistrée comme révoquée peut encore y être sélectionnée.

Là où rien n’est choisi, l’exclusion n’a rien sur quoi agir : une référence nommant une version exacte se résout vers cette version, et le retrait est annoncé plutôt qu’appliqué. Rien de tout cela ne change non plus ce qui vous est indiqué au moment du build — aggrega build signale chaque marqueur que le lockfile enregistre, quelle que soit la voie qui a épinglé la version.

Voir aussi

  • ./aggrega-sign.md — un marqueur est signé par son propre digest, donc les modes de signature et les identifiants requis par chacun sont ceux qui y sont décrits.
  • ./aggrega-serve.md — le daemon appose le même marqueur à aggrega/deprecateArtifact. Le contenu demandé dans un terminal est obligatoire dans une requête à cet endroit, car rien sur cette interface ne peut le demander.
  • ./aggrega-mcp.md — la même fonctionnalité sous la forme de l’outil deprecate-artifact, qu’un assistant peut appeler. Lisez ce que cette page dit sur son autorisation avant de le faire : un retrait change ce que résout chaque consommateur de ce registre.