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

aggrega config

Ispeziona e gestisce la configurazione del workspace

Sinossi

aggrega config

Descrizione

Inspect and manage the configuration Aggrega reads.
Most projects need two files.
One .aggrega-config.yaml at your project root, carrying a "workspace:" block —
that block is what marks the root — holds how this project builds: its catalog
directories, its provider bindings, which lint rules it relaxes. It is
committed, so a teammate who clones the project builds it the same way.
One global file is shared across every workspace on this machine:
~/.config/aggrega/config.yaml, or on Windows aggrega\config.yaml inside the
directory the APPDATA environment variable names. It holds what belongs to the
machine rather than to any one project: the registries you pull from and the
signature trust policy for each, how large the compiled-module store may grow,
any command extension you have installed. It loads automatically when it is
there, and nothing breaks when it is not.
Your project's file wins over the global one, an environment variable wins
over both, and a flag wins over everything.
Secrets are not configuration. A registry password or a signing identity token
is never a field in either file; it is supplied by environment variable or flag
at the moment it is needed.
Because the effective configuration is assembled rather than written anywhere,
"aggrega config show" is how you see what actually applies, and --origin is how
you find out which layer each setting came from. "aggrega config init" seeds a
working configuration, and "aggrega config capture" freezes the effective
build-critical settings into this workspace so a build does not depend on a
global file that is not committed.
Larger projects have more to work with. None of it is needed to start, and each
piece exists for the shape it solves:
More than one file inside a project. Every .aggrega-config.yaml from the
project root down to the directory you run in contributes, a nearer file
overriding a farther one. Only a file carrying "workspace:" marks the root;
one without it contributes settings without anchoring anything.
Extending a list instead of replacing it. A nearer file's list replaces the
farther one's. The companions catalog_dirs_append, governance_append,
linter_append, importer_append and providers_append concatenate onto the
resolved list at each layer instead of shadowing it.
A file your pipeline owns. .aggrega-config-append-ci.yaml may sit beside the
hand-authored file in any of those directories, so automation can overwrite
it wholesale without touching what a person wrote. It is additive only: it
removes nothing and overrides no scalar, and a scalar key written in it is
ignored and named in a warning. It never marks a root.
A relative path anchors to the file that declared it. A catalog directory, a
local plugin path, or an entry under a plugin's with.sources resolves against
the directory of the config file it was written in — not the project root,
and not the directory you ran the command from. So the same "./catalog" names
a different directory depending on which file carries it. Two settings sit
outside this rule: artifact_cache_dir is interpreted relative to the project
root wherever you run from, and AGGREGA_CATALOG_DIRS has no declaring file at
all, so supply absolute paths in it.
The other root markers. A "workspace:" block wins outright at whatever depth
it sits. Failing one, the nearest .aggrega/ directory or aggregate*.yaml,
release*.yaml or manifest*.yaml file anchors the root, in that order within a
directory; failing everything, your working directory is used.
--workspace-root skips discovery entirely.
Naming the global file. --config <path> wins over the AGGREGA_CONFIG
environment variable, which wins over the default location. Both name a file
deliberately, so a path either gives that does not exist is a loud error
rather than a silent fallback. Whichever file resolves is also the one a
config-writing command writes when it writes globally.

Sottocomandi

ComandoDescrizione
aggrega config captureCongela in questo workspace la configurazione effettiva critica per la build
aggrega config initInizializza una configurazione funzionante con un registry e la sua policy di trust
aggrega config showMostra la configurazione effettiva e da dove proviene ogni impostazione

Descrizione di aggrega config capture

Write the effective build-critical configuration into this project's workspace
config file, so the workspace builds identically without relying on the
machine's global configuration.
The build-critical subset is the configuration a build participates in: a set of
plugin socket attachments and the catalog directories. By default the captured
sockets are only those that determine the
rendered output — the provider bindings and the transform-role governance attachments — since only those must
travel with the project for byte-identical output. Pass --all-plugins to also
freeze the verdict-role governance, linter, and importer sockets, which otherwise stay free to
vary by environment. Each field is written at its effective value — the value
that resolves right now with the global configuration and the workspace tree
merged together — so a binding that today comes only from the global config is
materialized into the workspace and travels with the project.
Machine-wide tooling settings, such as a registry's trust policy, are not
captured: they stay in the global config by their nature. Capture always writes
this project's workspace config file. Running it again on an unchanged
configuration rewrites the same file byte-for-byte. Run in a folder that is not
inside a workspace, with no --workspace-root naming one, it writes nothing and
exits with an error saying so.

Flag di aggrega config capture

FlagPredefinitoDescrizione
--all-pluginsfalseCattura tutti i socket dei plugin, inclusi i gate di governance con ruolo verdict, di linter e di importer. Senza di esso, capture congela solo i socket che determinano l’output renderizzato (i binding dei provider e gli attachment di governance con ruolo transform).

Descrizione di aggrega config init

Seed a working configuration by registering a registry and its signature trust
policy, so a fresh machine can pull and verify signed artifacts without editing
YAML by hand.
By default it registers the official hub (hub.aggrega.ai) with signatures
required and the official trusted identities. The registry's advertised trust
policy is fetched once from its own origin and pinned locally — trust-on-first-
use; when the hub is unreachable, advertises nothing, or the workspace is
offline, its built-in official baseline is written instead, so init still
produces a usable config offline. Pass --registry to seed a different registry
(for an air-gapped or private hub). Such a registry has no built-in baseline,
so seeding it while the workspace is offline is refused: init takes no
identities or key to pin by hand, so register it once while online, or add it
with "aggrega registry add --identity" or "--key".
The entry is written to the global config shared across every workspace by
default; pass --workspace to write it to this project's workspace config
instead. If the target config file already exists, init refuses rather than
overwrite it — pass --force to write anyway (the registry entry is merged into
the existing file, other settings preserved).
Before anything else, init says where things are: the configuration file it
created — or, under --force, the one already there that it wrote into — and
the directory the machine-wide caches are kept in. On Windows that directory is
aggrega\cache inside the directory the LOCALAPPDATA environment variable names;
elsewhere it is a directory named aggrega under the per-user cache directory:
~/.cache/aggrega on Linux unless XDG_CACHE_HOME names another, and
~/Library/Caches/aggrega on macOS.
A seeded configuration is a document you own and go on editing, so --dry-run does
everything init does except write: it hands the content back, creating and
modifying nothing. The answer names the file the content is for — which matters
here, because the target is the global config unless --workspace selects this
project's own. A caller that keeps its own document model puts the content there,
where it is visible before it is saved and can be amended or undone. The registry
is still contacted for its advertised trust policy, because the policy in that
content is the policy a write would have pinned.
Because a dry run does everything else init does, it refuses an existing config
file exactly as a write refuses it, and for the same reason. So its exit code
predicts the write's: if the dry run refuses, init would have refused. Pass
--force alongside it to see the merge an overwriting write would produce.
Under --dry-run standard output carries that content and nothing else, so it stays
parseable. A registry seeded with no trust policy, because it advertises none,
still produces its notice, on standard error: read that stream too, or that
configuration arrives without the advice to pin identities by hand. A pinned
policy, whether advertised or the hub's built-in baseline, is in the content
itself and produces no notice.

Flag di aggrega config init

FlagPredefinitoDescrizione
--dry-runfalseFa tutto tranne scrivere: restituisce la configurazione inizializzata come contenuto, nominando il file a cui è destinata, e non crea né modifica nulla. Ogni altro comportamento è quello della scrittura, quindi un file di configurazione esistente viene rifiutato esattamente come lo rifiuta una scrittura — passa —force insieme a esso per ottenere l’unione che produrrebbe una scrittura con sovrascrittura.
--forcefalseSovrascrive un file di configurazione esistente. Senza di esso, init rifiuta quando il file di destinazione esiste già.
--globalfalseScrive la voce nella configurazione globale condivisa tra tutti i workspace. È il comportamento predefinito.
--registryhub.aggrega.aiHost del registry da inizializzare con la sua policy di trust. Il valore predefinito è l’hub ufficiale.
--workspacefalseScrive la voce nella configurazione del workspace di questo progetto invece che nella configurazione globale.

Descrizione di aggrega config show

Show the configuration that applies right now.
By default it leads with the cascade of config files and environment overrides
that contributed, lowest precedence first, then prints the effective merged
configuration — the global config, the workspace-tree cascade, and any
environment override combined into what applies right now.
Pass --global or --workspace to print a single layer's own file bytes verbatim,
preserving its comments and formatting; when that layer's file does not exist it
says so rather than failing. The two are mutually exclusive.
Pass --origin to annotate each effective setting with the layer it came from —
a command-line flag, an environment variable, a config file, or the built-in
defaults, highest precedence first. A flag is named as the reader typed it, so
a setting a flag decided reports that flag as its source. A setting is
attributed to the highest-precedence layer that sets it, whatever value that
layer writes: a file restating the default is the file named, not the built-in
defaults. List and map settings are attributed as a whole. The signing
requirement is the one exception: any layer may turn it on and none can turn it
off, so it names the first layer that turns it on.

Flag di aggrega config show

FlagPredefinitoDescrizione
--globalfalseStampa testualmente i byte del file di configurazione globale, preservandone commenti e formattazione.
--originfalseAnnota ogni impostazione effettiva con il livello da cui proviene (un flag della riga di comando, una variabile d’ambiente, un file di configurazione o i valori predefiniti integrati).
--workspacefalseStampa testualmente i byte del file di configurazione del workspace di questo progetto, preservandone commenti e formattazione.

Cosa fa

I sottocomandi config inizializzano, ispezionano e congelano la configurazione che governa una build. Per sapere in quale file va un’impostazione e come si combinano i livelli, vedi Configurazione — inizia con i due file di cui ha bisogno la maggior parte dei progetti e lascia il resto dietro di essi.

config init — inizializzare una configurazione funzionante

aggrega config init inizializza una configurazione su una macchina nuova registrando un registry e la sua policy di trust delle firme, così gli artifact firmati vengono scaricati e verificati senza modificare lo YAML a mano. Per impostazione predefinita registra l’hub ufficiale (hub.aggrega.ai) con le firme obbligatorie e le sue identità attendibili ufficiali. La policy di trust pubblicizzata dal registry viene recuperata una volta dalla sua origine e fissata localmente (trust-on-first-use); quando l’hub è irraggiungibile, non pubblicizza nulla o il workspace è offline, viene scritta invece la sua baseline ufficiale integrata, così init produce comunque una configurazione utilizzabile offline.

Prima di ogni altra cosa, init dice dove si trovano le cose. L’inizializzazione di una macchina Linux nuova si apre con:

Created the global configuration file at /home/you/.config/aggrega/config.yaml
Machine-wide caches are kept in /home/you/.cache/aggrega

e quella di una macchina Windows nuova con:

Created the global configuration file at C:\Users\you\AppData\Roaming\aggrega\config.yaml
Machine-wide caches are kept in C:\Users\you\AppData\Local\aggrega\cache

La prima riga nomina il file di configurazione scritto da init: Created quando il file non c’era, e Using quando c’era e --force ha permesso a init di scriverci; con --workspace nomina il file di configurazione del workspace invece di quello globale. La seconda nomina la directory in cui sono conservate le cache a livello di macchina — i plugin compilati e le loro descrizioni —, che è dove ogni piattaforma conserva le cache di un utente; Quali cache appartengono a questo progetto e quali alla macchina fornisce la regola per ogni piattaforma. Ogni riga termina con il suo percorso e nient’altro dopo, così il percorso può essere copiato così com’è. Le righe successive sono quelle della registrazione: che cosa ha trovato il recupero della policy di trust e in quale file è stato registrato il registry. Un’inizializzazione rifiutata non stampa nessuna delle due righe, poiché non ha creato nulla, e lo stesso vale per --dry-run, il cui standard output contiene solo il contenuto che restituisce.

  • --registry <host> inizializza un registry diverso — un hub air-gapped o privato — al posto di quello ufficiale. Un registry di questo tipo non ha una baseline integrata, quindi dove non pubblicizza nulla la voce viene scritta senza policy, e in un workspace offline la sua inizializzazione viene rifiutata (codice breve E0310): la policy non può essere recuperata, e init non accetta --identity o --key per fissarne una a mano. Inizializzalo una volta mentre sei online, oppure aggiungilo con aggrega registry add e una policy fornita da te.
  • Se il file di destinazione esiste già, init rifiuta anziché sovrascriverlo; --force scrive comunque, unendo la voce del registry nel file esistente e preservando le altre impostazioni.
  • --dry-run fa tutto ciò che fa init tranne scrivere. Restituisce la configurazione inizializzata come contenuto, senza creare né modificare nulla, e la risposta nomina il file a cui il contenuto è destinato — il che qui conta, perché la destinazione è la configurazione globale a meno che --workspace non selezioni quella di questo progetto. Un chiamante che mantiene un proprio modello del documento, come un editor, vi inserisce il contenuto, dove è visibile prima di essere salvato e può essere modificato o annullato.
  • Poiché un dry run fa tutto il resto che fa init, il suo codice di uscita anticipa quello della scrittura. Rifiuta un file di configurazione esistente esattamente come lo rifiuta una scrittura, e per lo stesso motivo, quindi puoi usarlo per chiedere se init riuscirebbe prima di impegnarti nella modifica. Per vedere il documento che produrrebbe una scrittura con sovrascrittura, passa --force insieme a esso: --force --dry-run riporta l’unione e continua a non scrivere nulla.
  • Il registry viene comunque contattato per la sua policy di trust pubblicizzata, perché la policy nel contenuto riportato è quella che una scrittura avrebbe fissato. Un dry run effettua verso l’origine di quel registry la stessa singola richiesta non autenticata che effettua una scrittura.
  • Con --dry-run, lo standard output contiene quel contenuto e nient’altro, così resta analizzabile. L’unica cosa che il contenuto non può esprimere è un’assenza: quando un registry non pubblicizza alcuna policy di trust e viene inizializzato senza, l’avviso che lo segnala — e che ti dice di fissare le identità con --identity o --key — va sullo standard error. Un documento di configurazione senza identità attendibili ha lo stesso aspetto sia che una policy sia stata fissata e risultasse vuota, sia che non ne sia stata pubblicizzata alcuna, quindi leggi entrambi i flussi; un programma che scarta lo standard error non ne viene informato. Quando il registry pubblicizza una policy, o al suo posto viene fissata la baseline integrata dell’hub ufficiale, la policy fissata si trova nel contenuto riportato stesso e non viene prodotto alcun avviso separato.

Una configurazione inizializzata è un documento di tua proprietà che continui a modificare, ed è per questo che può essere restituita anziché scritta. Congelare la configurazione effettiva, più avanti, produce un registro di ciò a cui la configurazione si è risolta — stato che il compilatore conserva su sé stesso anziché contenuto composto da qualcuno — quindi scrive sempre e non offre --dry-run.

config show — ispezionare ciò che si applica in questo momento

aggrega config show riporta la configurazione che si applica in questo momento. Nella vista predefinita parte dalla cascata di file di configurazione e override d’ambiente che hanno contribuito, dalla precedenza più bassa, quindi stampa la configurazione effettiva unita — la configurazione globale, la cascata dell’albero del workspace e qualsiasi sovrapposizione d’ambiente combinate in un unico risultato. Questa cascata dei file caricati è il punto in cui confermi quali file e override d’ambiente hanno dato forma alla configurazione attuale.

Due viste mirate restringono l’output:

  • --global o --workspace stampa testualmente i byte del file di un singolo livello, con commenti e formattazione preservati; quando il file di quel livello non esiste lo dice anziché fallire. I due si escludono a vicenda.
  • --origin annota ogni impostazione effettiva con il livello da cui proviene — un flag della riga di comando, una variabile d’ambiente, un file di configurazione o i valori predefiniti integrati, dalla precedenza più alta. Un flag è nominato come l’hai digitato, quindi un’impostazione decisa da --offline in questa esecuzione riporta --offline come origine; una variabile d’ambiente è nominata dopo un prefisso env: e un file di configurazione con il suo percorso assoluto.

Con --origin, un’impostazione è attribuita al livello con la precedenza più alta che la imposta, qualunque valore scriva quel livello. Così un file di progetto che scrive default_registry: hub.aggrega.ai viene nominato per quell’impostazione anche se il valore predefinito integrato è lo stesso registry, e un file di progetto che riafferma un valore già impostato dal file globale viene nominato al posto del file globale: in entrambi i casi è il file che mantiene il valore in essere, e quello la cui rimozione cambia la risposta il giorno in cui il valore predefinito o il file sottostante cambia. Un’impostazione che nessun livello imposta riporta i valori predefiniti integrati.

  • Che cosa conta come impostarla. Un file di configurazione imposta un’impostazione quando ne contiene la chiave, e un’impostazione di tipo elenco anche quando contiene il compagno _append dell’elenco. Una variabile d’ambiente imposta la sua impostazione quando è esportata con un valore non vuoto, e un flag quando lo digiti — --offline=false imposta la modalità con la stessa certezza di --offline.
  • Un file di configurazione di proprietà della tua pipeline viene nominato solo per le chiavi per cui viene letto, che sono le sue aggiunte agli elenchi e la policy di firma. Una chiave che ignora, e per cui emette un avviso, non viene mai riportata come origine di un valore.
  • Le impostazioni di tipo elenco e mappa sono attribuite nel loro insieme, al livello con la precedenza più alta che le imposta; quale livello abbia contribuito con quale voce di un elenco non viene riportato.
  • Il requisito di firma è l’unica eccezione. Qualsiasi livello può attivarlo e nessuno può disattivarlo, quindi nomina il primo livello che lo attiva. Un livello che scrive required: false non attiva nulla, quindi dove nessun livello lo attiva l’impostazione riporta i valori predefiniti integrati.

config capture — congelare le impostazioni critiche per la build

aggrega config capture scrive la configurazione effettiva critica per la build nel file di configurazione del workspace di questo progetto, così il workspace esegue build identiche senza dipendere dalla configurazione globale della macchina. Le impostazioni degli strumenti a livello di macchina, come la policy di trust di un registry, non vengono catturate; per loro natura restano nella configurazione globale. Eseguirlo di nuovo su una configurazione invariata riscrive lo stesso file byte per byte.

Il sottoinsieme catturato è un insieme di attachment ai socket dei plugin e le directory del catalogo:

  • Per impostazione predefinita capture congela solo i socket che determinano l’output renderizzato — i binding dei provider e gli attachment di governance con ruolo transform — poiché solo questi devono viaggiare con il progetto per avere build identiche byte per byte. Le directory del catalogo vengono sempre catturate.
  • --all-plugins estende i socket catturati per includere anche i socket di governance con ruolo verdict, di linter e di importer. Senza di esso quei tre restano liberi di variare a seconda dell’ambiente.

Capture scrive sempre, e non offre alcun modo per ricevere invece il contenuto. Ciò che produce è un registro di ciò a cui la configurazione si è risolta, non un documento composto da qualcuno, quindi non c’è nulla che un autore debba rivedere e modificare — riportarlo inviterebbe a modificare un’istantanea di una risoluzione.

La cattura scrive solo all’interno di un workspace. Eseguita in una cartella che non si trova all’interno di uno, senza --workspace-root né AGGREGA_WORKSPACE_ROOT che ne indichino uno, non scrive nulla — un file di configurazione scritto lì trasformerebbe la cartella in un workspace — e termina con un errore che lo segnala. aggrega config init --workspace rende prima la cartella un workspace.

Vedi anche

  • configuration.md — in quale file va un’impostazione, la scala di precedenza e i meccanismi a cui ricorre un progetto più grande.
  • global-flags.md — i flag --config e --workspace-root.
  • environment-variables.md — le variabili AGGREGA_* che sovrascrivono la configurazione in fase di esecuzione.
  • aggrega-registry.md — gestire direttamente i registry e la loro policy di trust.
  • aggrega-cache.md — che cosa contiene effettivamente la directory indicata da artifact_cache_dir, e perché un’entità che si trova lì e che nessun lockfile fissa non viene trovata da una build.