Variabili d’ambiente
La CLI aggrega legge un insieme fisso di variabili d’ambiente con prefisso AGGREGA_. Ciascuna sovrascrive a runtime l’impostazione corrispondente di .aggrega-config.yaml — il livello che un job di CI o un orchestratore che inietta segreti controlla senza modificare file tracciati — mentre un flag da riga di comando prevale comunque su tutto.
Precedenza
Una variabile d’ambiente si colloca sopra i file di configurazione committati — una sovrascrittura a runtime che una pipeline o un orchestratore che inietta segreti applica senza modificare un file tracciato — e sotto un flag da riga di comando, quindi un valore esplicito digitato sulla riga di comando non viene mai sovrascritto in silenzio dall’ambiente circostante. Configurazione riporta la scala completa e la stratificazione dei file sottostanti.
Una variabile non impostata (o vuota) passa al livello sottostante — non sovrascrive mai un valore configurato con un valore vuoto. Per vedere la configurazione che si applica in questo momento, e quale livello ha deciso ciascuna impostazione, esegui aggrega config show --origin.
Denominazione
Il nome di una variabile è AGGREGA_ seguito dal suo percorso di configurazione in upper snake case (i punti diventano underscore): signing.fulcio_url diventa AGGREGA_SIGNING_FULCIO_URL. Un nome è abbreviato per comodità — workspace.catalog_dirs corrisponde a AGGREGA_CATALOG_DIRS, in parallelo con PATH.
Le impostazioni per registry (registries[].*) non hanno una variabile d’ambiente: un elenco di blocchi di policy per host non si esprime come una singola variabile, e la policy di fiducia e di firma di un registry è configurazione committata, non una sovrascrittura dall’ambiente. Anche i flag situazionali, monouso e posizionali (--dry-run, --trace, --detail, --output, --skip-verify, --release, --entity e la famiglia lint --allow-*/--no-allow-*) non hanno variabile d’ambiente — sono decisioni per singola esecuzione.
Impostazioni supportate dalla configurazione
| Variabile | Percorso di configurazione | Note |
|---|---|---|
AGGREGA_DEFAULT_REGISTRY | default_registry | Host di destinazione/registry (hub.aggrega.ai per impostazione predefinita). Si scrive come si scrive default_registry in un file — vedi come si scrive l’host di un registry — e un valore scritto diversamente viene rifiutato quando la configurazione viene risolta, con il nome di questa variabile. |
AGGREGA_OFFLINE | offline | Booleano. Vieta ogni uscita di rete: ogni comando che scaricherebbe, farebbe pull, acquisirebbe, farebbe push, firmerebbe o contatterebbe un registry si rifiuta esplicitamente invece di connettersi, e una build attinge solo a ciò che la macchina ha già — il suo lockfile, la sua cache e le sue directory di catalogo locali, da cui --auto-pull riempie le entità di catalogo di un lockfile senza raggiungere un registry (una Recipe il cui chart viene scaricato da una sorgente remota si arresta comunque offline). La scoperta legge allora l’indice locale — l’avviso di deprecazione viene servito dall’indice costruito anziché sondato in tempo reale, e il livello di risoluzione del catalogo dal registry remoto viene saltato; il suggerimento di plugin che un comando non riconosciuto stampa legge solo l’indice locale, qualunque cosa dica questa impostazione. La verifica del materiale già in cache o fissato viene comunque eseguita — offline vieta lo scaricamento, non il controllo locale. --offline è il flag che sta sopra, in entrambe le direzioni: imposta la postura per un’esecuzione, e --offline=false consente la rete per un’esecuzione dove questa variabile o un file di configurazione l’hanno impostata. |
AGGREGA_AUTO_PULL | auto_pull | Booleano. Scarica automaticamente le dipendenze mancanti al momento della build. |
AGGREGA_ARTIFACT_CACHE_DIR | artifact_cache_dir | Directory della cache dei contenuti su disco, scritta relativa alla radice del workspace così da indicare la stessa directory ovunque venga eseguito il comando. Un valore assoluto viene rifiutato, così come uno che indica la radice del workspace stessa — dai alla cache una sua sottodirectory. |
AGGREGA_CATALOG_DIRS | workspace.catalog_dirs | Elenco separato dal separatore di percorsi del sistema operativo (: su Unix). Fornisci percorsi assoluti. Sostituisce l’elenco configurato; una Release a cui è dato un elenco proprio sotto workspace.releases mantiene quell’elenco. |
AGGREGA_SIGNING_FULCIO_URL | signing.fulcio_url | URL della CA Fulcio per la firma keyless. |
AGGREGA_SIGNING_REKOR_URL | signing.rekor_url | URL del transparency log Rekor per la firma keyless. |
AGGREGA_SIGNING_TIMESTAMP_URL | signing.timestamp_url | URL della timestamp authority RFC3161 per la firma keyless. |
AGGREGA_SIGNING_KEY_PATH | signing.key_path | Percorso di una chiave PEM ECDSA P-256 detenuta, per la firma con chiave. Solo un riferimento a un percorso — mai materiale di chiave. |
AGGREGA_SIGNING_REQUIRED | signing.required | Booleano. Richiede una firma per pubblicare e per consumare i tipi coperti da signing.kinds. Attiva il requisito e non lo disattiva mai: un file di configurazione che lo imposta lo mantiene impostato. |
AGGREGA_SIGNING_KINDS | signing.kinds | Elenco separato dal separatore di percorsi del sistema operativo (: su Unix), in cui ogni voce è un tipo scritto come il suo kind:, oppure all. Amplia i tipi coperti dal requisito e non li restringe mai; un valore che non è un tipo firmabile viene rifiutato, con il nome di questa variabile. |
AGGREGA_SKIP_SIGNATURE_VERIFICATION | skip_signature_verification | Booleano. Disabilita globalmente la verifica delle firme — in modo esplicito: ogni pull registra un avviso. |
AGGREGA_WORKSPACE_ROOT | (si abbina a --workspace-root) | Radice assoluta del workspace, che salta la scoperta — su ogni comando, e per ogni richiesta ad aggrega mcp che non indica un workspace proprio. Non è un campo di configurazione; il flag prevale quando è impostato. Impostata vuota, viene letta come non impostata — tranne da aggrega mcp su standard input e output con AGGREGA_BUNDLE_VERSION presente e senza --workspace-root, cioè l’avvio del bundle desktop con la sua impostazione Workspace folder vuota, che risponde a ogni chiamata che non indica un workspace proprio con un rifiuto che nomina quell’impostazione. Dove non indica una cartella esistente, ogni comando che legge il proprio workspace si rifiuta prima di fare qualsiasi altra cosa, aggrega serve e un listener di aggrega mcp si rifiutano di partire, e aggrega mcp su standard input e output parte comunque e risponde con il rifiuto a ogni chiamata che agisce in quel workspace — ciascuno nominando questa variabile insieme all’impostazione Workspace folder dell’applicazione desktop che la imposta, e citando il valore così come è stato dato. |
AGGREGA_BUNDLE_VERSION | (impostata dal bundle desktop) | La versione del bundle desktop che ha avviato aggrega mcp, che il bundle imposta nell’ambiente del server. Non è un campo di configurazione. Il server la legge una volta all’avvio e la riporta accanto alla propria versione su describe-capabilities chiamato senza argomenti, segnalando quando le due provengono da release diverse; nessun rifiuto è dovuto a una differenza. La sua presenza contrassegna anche l’avvio del bundle, quindi un AGGREGA_WORKSPACE_ROOT vuoto accanto a essa viene rifiutato anziché letto come non impostato, come descrive la riga sopra. Impostata vuota, viene letta come non impostata. |
AGGREGA_CONFIG punta a un file di configurazione globale esplicito da caricare sotto i file del progetto; seleziona quale file si applica anziché sovrascrivere una singola impostazione. Quando non è impostata, quel livello viene caricato automaticamente dalla posizione predefinita della piattaforma — su Windows aggrega\config.yaml all’interno della directory indicata dalla variabile d’ambiente APPDATA, e altrove aggrega/config.yaml all’interno della directory indicata da XDG_CONFIG_HOME, con ripiego su ~/.config/aggrega/config.yaml. Vedi Configurazione.
Dove si trovano i file propri della macchina
Il file di configurazione globale e le cache a livello di macchina si trovano dove ogni piattaforma conserva i file propri di un utente, quindi aggrega legge anche le variabili che indicano quei luoghi. Nessuna di esse è una variabile AGGREGA_ e nessuna sovrascrive un’impostazione: ciascuna dice dove si cerca un file quando nulla lo indica.
| Variabile | Letta su | Cosa colloca |
|---|---|---|
APPDATA | Windows | Il file di configurazione globale, in aggrega\config.yaml all’interno della directory indicata da APPDATA. |
LOCALAPPDATA | Windows | Le cache a livello di macchina, sotto aggrega\cache all’interno della directory indicata da LOCALAPPDATA. |
XDG_CONFIG_HOME, poi HOME | Linux, macOS e gli altri sistemi Unix | Il file di configurazione globale, in aggrega/config.yaml all’interno della directory indicata da XDG_CONFIG_HOME, oppure in ~/.config/aggrega/config.yaml quando XDG_CONFIG_HOME non è impostata. |
XDG_CACHE_HOME, poi HOME | Linux e gli altri sistemi Unix | Le cache a livello di macchina, sotto una directory aggrega all’interno di quella indicata da XDG_CACHE_HOME, oppure sotto ~/.cache/aggrega quando XDG_CACHE_HOME non è impostata. Un XDG_CACHE_HOME che non è un percorso assoluto non colloca alcuna cache, e i plugin compilati vengono allora conservati solo per l’esecuzione. |
HOME | macOS | Le cache a livello di macchina, sotto ~/Library/Caches/aggrega. |
AGGREGA_CONFIG, o --config, indica direttamente il file globale su ogni piattaforma e prevale su queste. Le cache proprie di un progetto non sono collocate da nessuna di esse: si trovano all’interno del progetto, sotto artifact_cache_dir. aggrega config init dice dove si trovano sia il file globale sia le cache a livello di macchina sulla macchina su cui viene eseguito.
Booleani
Una variabile booleana accetta true, false, 1 o 0 (senza distinzione tra maiuscole e minuscole). Qualsiasi altro valore non vuoto è un errore esplicito anziché un’ipotesi silenziosa — a differenza di YAML, yes/no/on/off non sono accettati.
Segreti
I segreti si forniscono tramite variabile d’ambiente o flag e non sono mai campi di configurazione.
| Variabile | Scopo | Precedenza |
|---|---|---|
AGGREGA_IDENTITY_TOKEN | Token di identità OIDC per la firma keyless. | Flag --identity-token > AGGREGA_IDENTITY_TOKEN > OIDC ambientale di GitHub Actions > SIGSTORE_ID_TOKEN. |
AGGREGA_REGISTRY_PASSWORD | Password del registry per aggrega login non interattivo. | --password-stdin > AGGREGA_REGISTRY_PASSWORD > prompt interattivo. |
SIGSTORE_ID_TOKEN è accettato come alias di interoperabilità con l’ecosistema sigstore per il token di identità, con priorità inferiore a AGGREGA_IDENTITY_TOKEN e all’endpoint ambientale di GitHub Actions. È la variabile che gli strumenti sigstore in generale impostano già.
La stessa risoluzione dell’identità serve tutti e tre i verbi di firma — aggrega push --sign, aggrega sign e aggrega deprecate. In un terminale interattivo ciascuno acquisisce un token di breve durata tramite un flusso nel browser, senza flag. Su GitHub Actions ciascuno conia automaticamente un nuovo token OIDC del workflow dall’endpoint ambientale del runner, quindi non serve esportare alcun token. Qualsiasi altra esecuzione non interattiva non ha né un terminale né un endpoint ambientale, quindi deve fornire il token esplicitamente (esporta AGGREGA_IDENTITY_TOKEN, oppure passa --identity-token). Senza un token fornito, senza endpoint ambientale e senza terminale, la firma keyless viene rifiutata anziché lasciata in sospeso.
Indicazioni per la CI (GitHub Actions)
Su GitHub Actions la CLI rileva l’endpoint OIDC ambientale del runner e conia automaticamente un nuovo token del workflow per ogni firma. Concedi al job il permesso di coniare un token e firma senza esportare alcun token:
permissions: id-token: write # allow the job to mint a workflow OIDC token# ...- run: aggrega push <entity> --signLo stesso vale per aggrega sign e aggrega deprecate. Per fissare un’identità specifica invece di quella coniata automaticamente, esporta esplicitamente AGGREGA_IDENTITY_TOKEN; un token esplicito (o --identity-token) prevale sempre sull’endpoint ambientale:
- run: | AGGREGA_IDENTITY_TOKEN=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \ "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sigstore" | jq -r .value) export AGGREGA_IDENTITY_TOKEN aggrega push <entity> --signUna CI che non è GitHub Actions non ha un endpoint ambientale: esporta AGGREGA_IDENTITY_TOKEN dal meccanismo OIDC di quel provider, oppure passa --identity-token.
Per un batch interattivo il corrispettivo è aggrega auth token, che esegue una volta il flusso OIDC nel browser e stampa il token di identità su stdout, così da poterlo esportare allo stesso modo:
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)Vedi aggrega-auth.md. Entrambe le strade permettono a un batch di invocazioni di aggrega sign di riutilizzare un’unica identità senza un passaggio nel browser per ogni artifact.
Preferisci --password-stdin a AGGREGA_REGISTRY_PASSWORD. Una variabile d’ambiente è leggibile dai processi figli e può persistere in una shell; stdin è la strada più sicura per la password. La variabile d’ambiente esiste come comodità per la CI.
Vedi anche
- configuration.md — in quale file va un’impostazione, e il modello di precedenza completo in cui si inseriscono queste variabili.
- global-flags.md —
--workspace-rooteAGGREGA_CONFIG. - aggrega-push.md e aggrega-sign.md — le variabili di firma e l’alias del token di identità.
- aggrega-auth.md —
aggrega auth tokenper acquisire interattivamente il token di identità. - aggrega-pull.md e aggrega-build.md — le variabili per offline, auto-pull, directory di catalogo e cache.
- ../../architecture/13-catalog-and-registry.md — le impostazioni di registry e di firma che diverse di queste variabili sovrascrivono.