Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

aggrega push-artifact

Pubblica un artefatto di dati autonomo (come un bundle di documentazione) in un registry OCI

Sinossi

aggrega push-artifact <file> [flags]

Descrizione

Publish a standalone data artifact — a documentation bundle or any other non-entity blob — to an OCI registry under the reserved docs/ namespace. Unlike push, which bundles a catalog entity and dispatches on its kind, push-artifact carries opaque bytes: it reads the file, packs it under the given media type (defaulting to the documentation-bundle media type), and tags it at docs/<name>:<tag>. The published artifact is signed separately by reference with aggrega sign. Beside it, push-artifact states when it published, as a small published-at attachment carrying this machine's clock in UTC to the second; the attachment moves no digest and changes no tag.

Flag

FlagPredefinitoDescrizione
--dry-runfalseCalcola il riferimento e stampa il : proposto; salta la chiamata di rete
--media-typeapplication/vnd.aggrega.docs.v1beta1+tar+gzMedia type dell’artefatto OCI; il valore predefinito è il media type del bundle di documentazione
--name—Nome dell’artefatto all’interno del namespace riservato docs/ (ad es. «aggrega-docs» pubblica in docs/aggrega-docs)
--registry—Host del registry di destinazione (sovrascrive il default_registry del workspace)
--tag—Tag di versione con cui pubblicare l’artefatto (obbligatorio)

L’artefatto del bundle di documentazione

Un bundle di documentazione è un artefatto di dati autonomo — un tar compresso con gzip di documentazione renderizzata — anziché un’entità di catalogo. Ha il media type application/vnd.aggrega.docs.v1beta1+tar+gz, che è il tipo di artefatto che un consumatore vede quando esegue il pull del bundle dal registry.

I bundle vengono pubblicati sotto il segmento di repository docs/: --name aggrega-docs colloca l’artefatto in docs/aggrega-docs, e --tag seleziona la versione, quindi la coordinata di pull è <registry>/docs/<name>:<tag> — per esempio, hub.aggrega.ai/docs/aggrega-docs:1.0.0. Poiché il bundle è un semplice artefatto di dati e non un’entità di catalogo, viene recuperato con qualsiasi client compatibile con OCI usando quel riferimento e quel media type. Il file pubblicato porta il nome indicato con --name, quindi un client che scrive i file per nome lo scrive con quel nome: oras pull hub.aggrega.ai/docs/aggrega-docs:1.0.0 lascia aggrega-docs nella directory corrente, byte per byte come è stato pubblicato.

Quando il registry fa fallire una scrittura

La pubblicazione scrive nel registry in più passaggi — il file, il manifest che lo nomina, il tag, e poi la data di pubblicazione accanto — e ciascuna di queste scritture 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, quindi una scrittura ritentata produce ciò che avrebbe prodotto un singolo tentativo.

Una scrittura che fallisce ancora dopo l’ultimo tentativo fa fallire il comando, e l’errore indica il passaggio. Un errore nell’allegare la data arriva dopo che l’artefatto è stato pubblicato: l’artefatto resta pubblicato, e il comando esce con codice diverso da zero dicendo che non è stato possibile allegare la sua data di pubblicazione. Eseguire di nuovo la stessa pubblicazione la completa: l’artefatto viene segnalato come già pubblicato, non viene caricato nulla, e la data viene allegata dove l’artefatto non ne ha, indicando l’orologio di quell’esecuzione — il momento in cui la pubblicazione è stata completata. A un artefatto che indica già una data non viene allegato nulla, e un elenco che non può essere letto esce con codice diverso da zero senza allegare nulla.

Offline

Pubblicare un artefatto richiede un round trip di rete, quindi in modalità offline — la chiave di primo livello offline in un file di configurazione, AGGREGA_OFFLINE o --offline — questo comando rifiuta prima di leggere il file, e il rifiuto indica quale di questi tre ha impostato la modalità. --dry-run continua a funzionare, perché calcola il riferimento e non effettua alcuna chiamata. Per pubblicare per una sola esecuzione da un workspace offline, passa --offline=false.

Vedi anche

  • ./aggrega-sign.md — un artefatto di dati viene firmato a posteriori, per riferimento; questo comando non allega alcuna firma propria.
  • ./aggrega-serve.md — il daemon offre la stessa pubblicazione in aggrega/publishArtifact, così un editor può eseguirla senza lasciare la sessione.
  • ./aggrega-mcp.md — la stessa funzionalità come strumento publish-artifact, che un assistente può chiamare. Leggi cosa dice quella pagina sul consentirlo prima di farlo.