aggrega deprecate
Collega un marcatore di deprecazione firmato a un artefatto già pubblicato
Sinossi
aggrega deprecate <reference> [flags]Descrizione
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.Flag
| Flag | Predefinito | Descrizione |
|---|---|---|
--from | — | File batch (YAML, o JSON come sottoinsieme) il cui elenco di primo livello allega un marcatore per voce. Ogni voce contiene reference, severity e reason, più replacement e message facoltativi. Mutuamente esclusivo con un riferimento posizionale e con —severity, —reason, —replacement e —message. |
--fulcio-url | — | URL dell’autorità di certificazione Fulcio per la firma keyless. Se omesso, viene usata l’istanza pubblica di Fulcio. |
--identity-token | — | Token di identità OIDC per la firma keyless. Facoltativo in un terminale interattivo (un flusso nel browser ne acquisisce uno) e su GitHub Actions (il token OIDC del workflow viene generato automaticamente); obbligatorio per altri usi non interattivi/CI, dove può invece essere esportato come AGGREGA_IDENTITY_TOKEN o SIGSTORE_ID_TOKEN. |
--key | — | Percorso di un PEM di chiave privata ECDSA P-256 posseduta, per la firma con chiave offline. Se omesso, viene usata la firma keyless. |
--message | — | Messaggio facoltativo conservato per l’audit e per la diagnostica registrata in fase di build; se non impostato, il valore predefinito è —reason. Rifiutato insieme a —from, le cui voci contengono il proprio. |
--reason | — | Motivo leggibile della deprecazione — perché è deprecato e che cosa fare invece. Obbligatorio con un riferimento posizionale, a meno che non lo fornisca un prompt interattivo; rifiutato insieme a —from, le cui voci contengono il proprio. |
--rekor-url | — | URL del transparency log Rekor per la firma keyless. Se omesso, viene usata l’istanza pubblica di Rekor. |
--replacement | — | Riferimento facoltativo all’artifact che sostituisce quello deprecato. Rifiutato insieme a —from, le cui voci contengono il proprio. |
--severity | — | Severità della deprecazione: una tra warning, error, retracted. Obbligatoria con un riferimento posizionale, a meno che non la fornisca un prompt interattivo; rifiutata insieme a —from, le cui voci contengono la propria. |
--timestamp-url | — | URL facoltativo della timestamp authority RFC3161 per la firma keyless. |
Da dove provengono gli endpoint di firma
Gli URL di Fulcio e Rekor per la firma keyless e il percorso della chiave per la firma con chiave possono provenire anche dal blocco signing: di .aggrega-config.yaml (globale e per registry, dove un valore impostato per il registry dell’artefatto ha la precedenza su quello globale, campo per campo); un flag sovrascrive la configurazione, e la configurazione sovrascrive il default public-good. Quindi le istanze public-good indicate nella tabella dei flag vengono usate solo dove né un flag né la configurazione del tuo workspace indicano un endpoint. Il marcatore viene firmato esattamente come aggrega sign firma un artefatto.
Quando il registry fa fallire una scrittura
Deprecare un artifact scrive nel registry due volte: il marcatore, allegato come referrer dell’artifact, e poi la firma del marcatore, allegata come referrer del marcatore. Ogni scrittura viene ritentata quando il registry o la rete la fanno fallire in un modo in cui un tentativo successivo può riuscire, come un errore del server, un timeout o una connessione reimpostata; aggrega push elenca questi errori. Una scrittura viene tentata al massimo tre volte, a mezzo secondo e poi a un secondo di distanza, e ogni tentativo è un nuovo caricamento degli stessi byte anziché un nuovo invio della richiesta fallita. Il timestamp del marcatore viene apposto una sola volta, prima del primo tentativo, quindi una scrittura ritentata lascia un solo marcatore e una sola firma, non due.
La firma del marcatore, tra le due scritture, non viene ritentata nel suo insieme; all’interno di una firma keyless, una richiesta a cui l’autorità di certificazione, il log di trasparenza o l’autorità di marcatura temporale risponde con 429 Too Many Requests o con un errore del server viene inviata di nuovo a quel servizio, come descrive aggrega sign. Una scrittura che fallisce ancora dopo l’ultimo tentativo, o una firma che fallisce, arresta il comando e nomina il passaggio; un marcatore già allegato a quel punto resta allegato senza la sua firma. Con --from, le voci allegate prima di quella fallita restano allegate.
Un file batch contiene il contenuto di ciascun marcatore
Con --from, la severità, il motivo, la sostituzione e il messaggio di ogni marcatore provengono dalla sua voce nel file batch. Un --severity, --reason, --replacement o --message passato insieme a --from viene quindi rifiutato anziché ignorato: il comando nomina ciascuno di quelli passati e si arresta prima che il file batch venga letto, così nessun marcatore viene allegato. Inserisci il contenuto nelle voci del file, oppure depreca un singolo riferimento con i suoi flag di contenuto.
Un batch viene firmato con una sola credenziale
Con --from, ogni marcatore nel file batch viene firmato con la stessa credenziale: una singola chiave posseduta, o una singola identità keyless richiesta una volta per l’intero file. Quale delle due serva a una voce è deciso dalla configurazione per il registry del suo riferimento — un signing.key_path che si applica a quel registry seleziona la chiave che indica, e dove non se ne applica nessuno il marcatore viene firmato keyless. Quando le voci richiederebbero credenziali diverse — la configurazione indica una chiave per un registry e nessuna per un altro, oppure due chiavi diverse — nessun marcatore viene allegato e il comando nomina i registry da ciascun lato. Lo fa prima che venga richiesta qualsiasi identità e prima che venga letto qualsiasi registry.
Dividi il file in un batch per credenziale, oppure passa una sola chiave con --key, che si applica a ogni voce qualunque cosa dica la configurazione per ciascun registry. Il messaggio è descritto in References signed together need different signing credentials (I riferimenti firmati insieme richiedono credenziali di firma diverse).
Anche il firmatario di ogni voce viene preparato prima che venga allegato il primo marcatore, quindi una chiave che non può essere letta, o un token di identità fornito che non contiene alcun subject utilizzabile, arresta il batch senza che nulla sia stato allegato.
Che cosa fa ciascuna severità
Le tre severità formano un insieme ordinato — warning, poi error, poi retracted — e si dividono in due livelli che differiscono per quando agiscono.
warning ed error sono livelli consultivi. Un marcatore con una di queste severità non cambia mai la versione a cui si risolve un riferimento. Viene registrato quando esegui aggrega pull, e ogni superficie che legge il lockfile lo riporta.
Ognuna di queste superfici riporta ogni riferimento deprecato fissato dal lockfile, qualunque sia la severità, nominando il riferimento, la sua severità, il suo messaggio e quando il record è stato osservato:
| Superficie | Che cosa fa con un marcatore registrato |
|---|---|
aggrega build | Lo riporta, e si arresta se hai configurato un arresto a quella severità. |
aggrega validate --release | Lo riporta. Il verdetto non cambia. |
aggrega lint --release | Lo riporta. Il verdetto non cambia. |
aggrega serve | Lo pubblica nel tuo editor come avviso mentre l’Aggregate è aperto. Un marcatore nomina un riferimento o un plugin anziché un documento del tuo workspace, quindi resta sull’Aggregate; solo gli errori di mappatura propri di un Manifest sono mostrati sul Manifest. |
Lo strumento build nativo per l’IA | Lo riporta, e rifiuta se hai configurato un arresto a quella severità. |
Gli strumenti describe e validate nativi per l’IA | Lo riportano insieme al proprio output. |
Se un marcatore arresti anche una build è un’impostazione separata: build.halt_on_deprecated_severity non è impostato per impostazione predefinita, quindi nulla si arresta, e impostarlo su una severità arresta a quella severità e a quelle superiori. Governa la build — aggrega build e lo strumento di build nativo per l’IA, che è la stessa operazione — e nient’altro: le superfici di segnalazione nominano il marcatore e proseguono in ogni caso. Alzare la soglia non riduce mai ciò che ti viene comunicato, su nessuna superficie — ricevi comunque l’avviso per tutto ciò che sta sotto di essa, e per tutto ciò che l’arresto non copre.
Alcuni plugin sono registrati altrove, e i loro marcatori provengono da lì. Un attachment plugins.linter, e un attachment plugins.governance con ruolo ir-verdict o render-verdict, non danno forma ad alcuna parte dell’output renderizzato, quindi sono fissati in plugins-trust.yaml accanto al lockfile anziché nel lockfile stesso. Ogni record lì contiene il marcatore scoperto per il plugin che nomina, insieme alla sua identità, e aggrega pull ne registra uno nello stesso modo in cui registra un marcatore su una riga del lockfile.
aggrega build, aggrega lint --release e aggrega validate --release leggono entrambi i record, quindi un plugin deprecato viene nominato lì proprio come un riferimento deprecato, e build.halt_on_deprecated_severity governa entrambi allo stesso modo. Due differenze meritano di essere conosciute. L’avviso per un plugin di questo tipo non dice quando il record è stato osservato — quel file non contiene alcun timestamp, ed è ciò che gli permette di riprodursi byte per byte — quindi nomina invece da dove proviene il dato e il comando che lo aggiorna. Inoltre una voce lì non viene mai riscritta da un pull ordinario: un marcatore appena pubblicato viene aggiunto al record che il plugin ha già, mentre l’identità a cui è vincolato resta invariata finché non chiedi di cambiarla con aggrega pull --upgrade.
retracted è il livello di ritiro, e agisce anche prima. Una versione registrata come ritirata viene esclusa dalla valutazione quando aggrega pull sceglie una versione per un riferimento che non ne indicava una. Se un’altra versione pubblicata soddisfa il riferimento, viene presa quella versione e il pull lo dice, nominando la versione saltata, il motivo registrato contro di essa e la versione presa al suo posto. Se non resta alcuna versione pubblicata che soddisfi il riferimento, il pull si arresta e dice che ogni candidata è stata ritirata — non riporta l’entità come mancante e non ripiega mai in silenzio.
Indicare esplicitamente una versione prevale sul ritiro
Un riferimento che indica una versione esatta si risolve sempre in quella versione, che sia stata ritirata o meno. Indicare la versione è l’override, quindi non esiste un’impostazione separata per disattivare l’esclusione — e una versione fissata da un precedente aggrega pull continua a risolversi esattamente per lo stesso motivo.
Il pull lo dichiara apertamente quando la versione che hai indicato è stata ritirata, così la build che vi si era già impegnata continua a funzionare mentre puoi comunque vedere perché potresti voler passare ad altro.
I record di ritiro sono un’istantanea, non una risposta in tempo reale
Un artifact pubblicato è immutabile, ma un ritiro no: una versione può essere ritirata dopo l’ultima volta che hai controllato. L’esclusione legge ciò che il tuo workspace ha registrato l’ultima volta che ha costruito il proprio indice locale del registry, quindi ti protegge dal selezionare una versione nota come ritirata. Non può dirti che una versione non è ritirata in questo momento.
Ogni segnalazione di un marcatore registrato in precedenza indica quando quel record è stato osservato, così un record obsoleto è distinguibile da uno recente, e ognuna nomina il comando che lo aggiorna. Vengono conservati due record, che si aggiornano separatamente: l’esclusione delle versioni e aggrega inspect leggono il tuo indice locale del registry, che viene aggiornato da aggrega registry update, mentre aggrega build legge il marcatore registrato nel lockfile, che viene aggiornato da aggrega pull. Ciò che aggrega pull stampa mentre cerca non riporta alcun momento di questo tipo — riporta ciò che ha trovato in quell’istante.
Per lo stesso motivo, l’assenza di un ritiro non è la prova che non ne esista alcuno — solo che nessuno era stato registrato l’ultima volta che hai aggiornato.
Dove vieni informato
Quale comando ti informa di un ritiro dipende da quale registrazione legge. La tabella più sopra riguarda il marcatore registrato nel tuo lockfile — ciò che questa Release ha fissato. Questa riguarda l’indice locale del registry — ciò che un registry ha pubblicato — che è la registrazione letta dall’esclusione delle versioni.
| Comando | Cosa ti dice di un ritiro registrato |
|---|---|
aggrega registry update | Nomina ogni marcatore che incontra mentre percorre il registry: il repository, la versione su cui è stato registrato, la gravità e se il marcatore è stato registrato. Ciascun registry riporta poi quanti marcatori contiene ora il suo indice. |
aggrega search | Riporta la versione che una risoluzione prenderebbe invece di una revocata, e nomina le versioni revocate in una colonna NOTES. --include-retracted riporta invece la versione pubblicata più alta. |
aggrega inspect | Stampa la gravità registrata sotto l’entità, con la versione su cui è stata registrata, il motivo, la sostituzione dove ne è indicata una e la data di emissione — per ogni tipo che risolve per nome. |
aggrega pull | Nomina ogni versione che ha saltato, il motivo registrato a suo carico e la versione presa al suo posto. Una versione che hai nominato esplicitamente viene comunque risolta, e il ritiro viene annunciato anziché applicato. |
aggrega plugin add | Lo stesso: una versione che sceglie viene vagliata su entrambe le vie con cui ne risolve una, e una versione che indichi come <name>:<version> viene comunque risolta, con il ritiro annunciato. Dove non è stato possibile leggere i marcatori, lo dice e dichiara che le versioni pubblicate non sono state vagliate. |
aggrega build | Nulla da questa registrazione. Legge solo il tuo lockfile e mai l’indice, quindi ciò che riporta è il marcatore registrato a carico della versione che hai fissato. |
aggrega serve | Nulla da questa registrazione. La sua risoluzione non consulta le registrazioni dei ritiri, quindi lì una versione revocata può ancora essere selezionata; pubblica il marcatore del lockfile al tuo editor. |
Leggi le ultime due righe insieme alle altre: un comando ti informa di un ritiro solo dove sta facendo qualcosa su cui il ritiro incide — scegliere una versione, o mostrarti cosa ha detto un publisher. Il silenzio di un comando che non fa né l’una né l’altra cosa non è prova che non ci sia nulla di registrato.
Un avviso nomina la gravità registrata dal publisher. Un artefatto revocato viene riportato come retracted; le due gravità consultive vengono riportate come deprecate, indicando quale delle due. Così ciò che rileggi corrisponde al valore che è stato scritto e al valore con cui configureresti una soglia di arresto.
Due tipi di avviso sono tenuti separati perché riportano eventi diversi. Una riga deprecation: ti dice qualcosa su un artefatto. Una riga retraction: ti dice cosa non hai ottenuto — una versione che è stata saltata, o un vaglio che non è stato possibile eseguire. Dove un comando le emette entrambe sullo stesso artefatto, sono due fatti e non una stessa affermazione fatta due volte.
Quali risoluzioni copre l’esclusione
L’esclusione agisce ovunque un comando sceglie una versione per te. Questa è la regola, e stabilisce se una determinata risoluzione è coperta.
aggrega pull la applica ovunque scelga una versione per un riferimento che non ne indicava una — qualunque cosa il riferimento nomini: un’entità del catalogo, una libreria, un Aggregate pubblicato. Un’unica regola le governa tutte, quindi la versione in cui un riferimento si risolve non dipende da quale tipo di riferimento l’ha richiesta.
aggrega plugin add la applica su ogni via con cui risolve un riferimento a un plugin non fissato: rispetto alle versioni pubblicate che il tuo indice locale del registry contiene già, e rispetto all’elenco live delle versioni a cui ricorre quando quell’indice non contiene il repository. Una versione ritirata viene saltata, e la sostituzione annunciata, su qualunque via l’abbia risolta.
Il daemon rivolto all’editor è l’eccezione. Risolve i riferimenti su richiesta mentre serve un editor, e quella risoluzione sceglie le versioni senza consultare le registrazioni dei ritiri, quindi lì una versione registrata come revocata può ancora essere selezionata.
Dove non viene scelto nulla, l’esclusione non ha nulla su cui agire: un riferimento che nomina una versione esatta si risolve in quella versione, e il ritiro viene annunciato anziché applicato. Né nulla di tutto ciò cambia ciò che ti viene detto al momento della build — aggrega build riporta ogni marcatore registrato nel lockfile, qualunque via abbia fissato la versione.
Vedi anche
- ./aggrega-sign.md — un marcatore è firmato tramite il proprio digest, quindi le modalità di firma e le credenziali che ciascuna richiede sono quelle descritte lì.
- ./aggrega-serve.md — il daemon allega lo stesso marcatore su
aggrega/deprecateArtifact. Il contenuto che viene chiesto in un terminale è obbligatorio in una richiesta lì, perché nulla su quella superficie può chiederlo. - ./aggrega-mcp.md — la stessa funzionalità come strumento
deprecate-artifact, che un assistente può chiamare. Leggi cosa dice quella pagina sul consentirlo prima di farlo: un ritiro cambia ciò che risolve ogni consumatore di quel registry.