Umgebungsvariablen
Die aggrega-CLI liest einen festen Satz von Umgebungsvariablen mit dem Präfix AGGREGA_. Jede übersteuert zur Laufzeit die entsprechende Einstellung in .aggrega-config.yaml — die Ebene, die ein CI-Job oder ein Geheimnisse injizierender Orchestrator steuert, ohne versionierte Dateien zu bearbeiten —, während ein Kommandozeilen-Flag weiterhin über allem steht.
Rangfolge
Eine Umgebungsvariable steht über den committeten Konfigurationsdateien — eine Laufzeitübersteuerung, die eine Pipeline oder ein Geheimnisse injizierender Orchestrator anwendet, ohne eine versionierte Datei zu bearbeiten — und unter einem Kommandozeilen-Flag, sodass ein expliziter, auf der Kommandozeile eingegebener Wert nie stillschweigend von der umgebenden Umgebung übersteuert wird. Konfiguration beschreibt die vollständige Rangfolge und die Schichtung der darunterliegenden Dateien.
Eine nicht gesetzte (oder leere) Variable fällt auf die darunterliegende Ebene durch — sie überschreibt nie einen konfigurierten Wert mit einem leeren. Um die gerade geltende Konfiguration zu sehen und welche Ebene jede Einstellung entschieden hat, führen Sie aggrega config show --origin aus.
Benennung
Ein Variablenname ist AGGREGA_, gefolgt von seinem Konfigurationspfad in Upper-Snake-Case (Punkte werden zu Unterstrichen): signing.fulcio_url wird zu AGGREGA_SIGNING_FULCIO_URL. Ein Name ist der Ergonomie halber verkürzt — workspace.catalog_dirs wird an AGGREGA_CATALOG_DIRS gebunden, in Anlehnung an PATH.
Registry-spezifische Einstellungen (registries[].*) haben keine Umgebungsvariable: Eine Liste hostspezifischer Richtlinienblöcke lässt sich nicht als einzelne Variable ausdrücken, und die Vertrauens- und Signaturrichtlinie einer Registry ist committete Konfiguration, keine Übersteuerung aus der Umgebung. Situative, einmalige und positionsbezogene Flags (--dry-run, --trace, --detail, --output, --skip-verify, --release, --entity und die Familie lint --allow-*/--no-allow-*) haben ebenfalls keine Umgebungsvariable — sie sind Entscheidungen pro Ausführung.
Konfigurationsgestützte Einstellungen
| Variable | Konfigurationspfad | Hinweise |
|---|---|---|
AGGREGA_DEFAULT_REGISTRY | default_registry | Ziel-/Registry-Host (standardmäßig hub.aggrega.ai). So geschrieben, wie default_registry in einer Datei geschrieben wird — siehe wie ein Registry-Host geschrieben wird —, und ein anders geschriebener Wert wird beim Auflösen der Konfiguration unter Nennung dieser Variable abgewiesen. |
AGGREGA_OFFLINE | offline | Boolesch. Verbietet jeden ausgehenden Netzwerkverkehr: Jeder Befehl, der abrufen, pullen, beziehen, pushen, signieren oder eine Registry kontaktieren würde, verweigert dies deutlich, statt eine Verbindung aufzubauen, und ein Build greift nur auf das zurück, was der Rechner bereits hat — seine Lockdatei, seinen Cache und seine lokalen Katalogverzeichnisse, aus denen --auto-pull die Katalogentitäten einer Lockdatei füllt, ohne eine Registry zu erreichen (ein Recipe, dessen Chart aus einer entfernten Quelle abgerufen wird, bricht offline dennoch ab). Die Erkennung liest dann den lokalen Index — der Deprecation-Hinweis wird aus dem erstellten Index bereitgestellt statt live abgefragt, und die Katalogauflösungsstufe über die entfernte Registry wird übersprungen; der Plugin-Hinweis, den ein unbekannter Befehl ausgibt, liest unabhängig von dieser Einstellung nur den lokalen Index. Die Prüfung bereits gecachten oder gepinnten Materials läuft weiterhin — offline verbietet den Abruf, nicht die lokale Prüfung. --offline ist das Flag darüber, in beiden Richtungen: Es setzt die Haltung für eine Ausführung, und --offline=false erlaubt das Netzwerk für eine Ausführung, wo diese Variable oder eine Konfigurationsdatei sie gesetzt hat. |
AGGREGA_AUTO_PULL | auto_pull | Boolesch. Fehlende Abhängigkeiten beim Build automatisch abrufen. |
AGGREGA_ARTIFACT_CACHE_DIR | artifact_cache_dir | Verzeichnis des Inhalts-Caches auf der Festplatte, relativ zum Workspace-Stamm geschrieben, sodass es dasselbe Verzeichnis nennt, wo auch immer der Befehl läuft. Ein absoluter Wert wird abgewiesen, ebenso einer, der den Workspace-Stamm selbst nennt — geben Sie dem Cache ein eigenes Unterverzeichnis. |
AGGREGA_CATALOG_DIRS | workspace.catalog_dirs | Durch das Pfadlisten-Trennzeichen des Betriebssystems getrennt (: unter Unix). Geben Sie absolute Pfade an. Ersetzt die konfigurierte Liste; ein Release, dem unter workspace.releases eine eigene Liste gegeben ist, behält diese Liste. |
AGGREGA_SIGNING_FULCIO_URL | signing.fulcio_url | URL der Fulcio-CA für schlüsselloses Signieren. |
AGGREGA_SIGNING_REKOR_URL | signing.rekor_url | URL des Rekor-Transparenzprotokolls für schlüsselloses Signieren. |
AGGREGA_SIGNING_TIMESTAMP_URL | signing.timestamp_url | URL der RFC3161-Zeitstempelstelle für schlüsselloses Signieren. |
AGGREGA_SIGNING_KEY_PATH | signing.key_path | Pfad zu einer vorgehaltenen ECDSA-P-256-Schlüssel-PEM für schlüsselbasiertes Signieren. Nur ein Pfadverweis — nie Schlüsselmaterial. |
AGGREGA_SIGNING_REQUIRED | signing.required | Boolesch. Verlangt eine Signatur, um die Arten, die signing.kinds abdeckt, zu veröffentlichen und zu konsumieren. Sie schaltet die Anforderung ein und nie aus: Eine Konfigurationsdatei, die sie setzt, hält sie gesetzt. |
AGGREGA_SIGNING_KINDS | signing.kinds | Durch das Pfadlisten-Trennzeichen des Betriebssystems getrennt (: unter Unix), jeder Eintrag eine Art so, wie ihr kind: geschrieben wird, oder all. Sie erweitert die Arten, die die Anforderung abdeckt, und schränkt sie nie ein; ein Wert, der keine signierbare Art ist, wird unter Nennung dieser Variable abgewiesen. |
AGGREGA_SKIP_SIGNATURE_VERIFICATION | skip_signature_verification | Boolesch. Deaktiviert global die Signaturprüfung — deutlich sichtbar: Jeder Pull protokolliert eine Warnung. |
AGGREGA_WORKSPACE_ROOT | (gehört zu --workspace-root) | Absoluter Workspace-Stamm, der die Erkennung überspringt — bei jedem Befehl und für jede Anfrage an aggrega mcp, die keinen eigenen Workspace nennt. Kein Konfigurationsfeld; das Flag gewinnt, wenn es gesetzt ist. Leer gesetzt, wird sie als nicht gesetzt gelesen — außer von aggrega mcp über Standardein- und -ausgabe mit AGGREGA_BUNDLE_VERSION und ohne --workspace-root, also dem Start durch das Desktop-Bundle mit leerer Einstellung Workspace folder, das jeden Aufruf, der keinen eigenen Workspace nennt, mit einer Abweisung beantwortet, die diese Einstellung nennt. Wo sie keinen existierenden Ordner nennt, verweigert jeder Befehl, der seinen Workspace liest, die Ausführung, bevor er irgendetwas anderes tut, aggrega serve und ein aggrega mcp-Listener verweigern den Start, und aggrega mcp über Standardein- und -ausgabe startet trotzdem und beantwortet jeden Aufruf, der in diesem Workspace handelt, mit der Abweisung — jede nennt diese Variable zusammen mit der Einstellung Workspace folder der Desktop-Anwendung, die sie setzt, und zitiert den Wert so, wie er angegeben wurde. |
AGGREGA_BUNDLE_VERSION | (vom Desktop-Bundle gesetzt) | Die Version des Desktop-Bundles, das aggrega mcp gestartet hat; das Bundle setzt sie in der Umgebung des Servers. Kein Konfigurationsfeld. Der Server liest sie einmal beim Start und meldet sie neben seiner eigenen Version bei describe-capabilities, wenn es ohne Argumente aufgerufen wird, und gibt an, wenn die beiden aus unterschiedlichen Releases stammen; bei einer Abweichung wird nichts abgewiesen. Ihr Vorhandensein kennzeichnet zudem den Start durch das Bundle, sodass eine leere AGGREGA_WORKSPACE_ROOT daneben abgewiesen statt als nicht gesetzt gelesen wird, wie die Zeile darüber beschreibt. Leer gesetzt, wird sie als nicht gesetzt gelesen. |
AGGREGA_CONFIG verweist auf eine explizite globale Konfigurationsdatei, die unterhalb der eigenen Dateien des Projekts geladen wird; sie bestimmt, welche Datei gilt, statt eine einzelne Einstellung zu übersteuern. Ist sie nicht gesetzt, wird diese Ebene automatisch vom Standardort der Plattform geladen — unter Windows aggrega\config.yaml in dem Verzeichnis, das die Umgebungsvariable APPDATA nennt, und anderswo aggrega/config.yaml in dem Verzeichnis, das XDG_CONFIG_HOME nennt, mit ~/.config/aggrega/config.yaml als Rückfall. Siehe Konfiguration.
Wo die eigenen Dateien des Rechners liegen
Die globale Konfigurationsdatei und die rechnerweiten Caches liegen dort, wo jede Plattform die eigenen Dateien eines Benutzers ablegt, daher liest aggrega auch die Variablen, die diese Orte nennen. Keine davon ist eine AGGREGA_-Variable, und keine übersteuert eine Einstellung: Jede gibt an, wo nach einer Datei gesucht wird, wenn nichts sie nennt.
| Variable | Gelesen unter | Was sie festlegt |
|---|---|---|
APPDATA | Windows | Die globale Konfigurationsdatei, unter aggrega\config.yaml in dem Verzeichnis, das APPDATA nennt. |
LOCALAPPDATA | Windows | Die rechnerweiten Caches, unter aggrega\cache in dem Verzeichnis, das LOCALAPPDATA nennt. |
XDG_CONFIG_HOME, dann HOME | Linux, macOS und die anderen Unix-Systeme | Die globale Konfigurationsdatei, unter aggrega/config.yaml in dem Verzeichnis, das XDG_CONFIG_HOME nennt, oder unter ~/.config/aggrega/config.yaml, wenn XDG_CONFIG_HOME nicht gesetzt ist. |
XDG_CACHE_HOME, dann HOME | Linux und die anderen Unix-Systeme | Die rechnerweiten Caches, unter einem aggrega-Verzeichnis in dem Verzeichnis, das XDG_CACHE_HOME nennt, oder unter ~/.cache/aggrega, wenn XDG_CACHE_HOME nicht gesetzt ist. Eine XDG_CACHE_HOME, die kein absoluter Pfad ist, legt keinen Cache fest, und kompilierte Plugins werden dann nur für die Ausführung behalten. |
HOME | macOS | Die rechnerweiten Caches, unter ~/Library/Caches/aggrega. |
AGGREGA_CONFIG oder --config nennt die globale Datei auf jeder Plattform direkt und hat Vorrang vor diesen. Die eigenen Caches eines Projekts werden von keiner davon festgelegt: Sie liegen innerhalb des Projekts, unter artifact_cache_dir. aggrega config init gibt an, wo sich auf dem Rechner, auf dem es läuft, sowohl die globale Datei als auch die rechnerweiten Caches befinden.
Boolesche Werte
Eine boolesche Variable akzeptiert true, false, 1 oder 0 (ohne Unterscheidung von Groß- und Kleinschreibung). Jeder andere nicht leere Wert ist ein deutlicher Fehler statt einer stillen Vermutung — anders als bei YAML werden yes/no/on/off nicht akzeptiert.
Geheimnisse
Geheimnisse werden per Umgebungsvariable oder Flag übergeben und sind nie Konfigurationsfelder.
| Variable | Zweck | Rangfolge |
|---|---|---|
AGGREGA_IDENTITY_TOKEN | OIDC-Identitätstoken für schlüsselloses Signieren. | Flag --identity-token > AGGREGA_IDENTITY_TOKEN > Umgebungs-OIDC von GitHub Actions > SIGSTORE_ID_TOKEN. |
AGGREGA_REGISTRY_PASSWORD | Registry-Passwort für nicht interaktives aggrega login. | --password-stdin > AGGREGA_REGISTRY_PASSWORD > interaktive Eingabeaufforderung. |
SIGSTORE_ID_TOKEN wird als Interop-Alias des Sigstore-Ökosystems für das Identitätstoken berücksichtigt, mit niedrigerem Rang als AGGREGA_IDENTITY_TOKEN und der Umgebungs-Schnittstelle von GitHub Actions. Es ist die Variable, die die breitere Sigstore-Werkzeuglandschaft bereits setzt.
Dieselbe Identitätsauflösung dient allen drei Signaturbefehlen — aggrega push --sign, aggrega sign und aggrega deprecate. An einem interaktiven Terminal bezieht jeder ohne Flags über einen Browser-Ablauf ein kurzlebiges Token. Unter GitHub Actions erzeugt jeder automatisch ein frisches Workflow-OIDC-Token über den Umgebungs-Endpunkt des Runners, sodass kein Token-Export nötig ist. Jede andere nicht interaktive Ausführung hat weder ein Terminal noch einen Umgebungs-Endpunkt und muss das Token daher explizit übergeben (AGGREGA_IDENTITY_TOKEN exportieren oder --identity-token übergeben). Ohne übergebenes Token, ohne Umgebungs-Endpunkt und ohne Terminal wird schlüsselloses Signieren abgewiesen, statt hängen zu bleiben.
CI-Hinweise (GitHub Actions)
Unter GitHub Actions erkennt die CLI den Umgebungs-OIDC-Endpunkt des Runners und erzeugt für jede Signatur automatisch ein frisches Workflow-Token. Erteilen Sie dem Job die Berechtigung, ein Token zu erzeugen, und signieren Sie ohne Token-Export:
permissions: id-token: write # allow the job to mint a workflow OIDC token# ...- run: aggrega push <entity> --signDasselbe gilt für aggrega sign und aggrega deprecate. Um statt des automatisch erzeugten eine bestimmte Identität festzulegen, exportieren Sie AGGREGA_IDENTITY_TOKEN explizit; ein explizites Token (oder --identity-token) hat stets Vorrang vor dem Umgebungs-Endpunkt:
- 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> --signEine CI, die nicht GitHub Actions ist, hat keinen Umgebungs-Endpunkt: Exportieren Sie AGGREGA_IDENTITY_TOKEN aus dem OIDC-Mechanismus dieses Anbieters oder übergeben Sie --identity-token.
Für einen interaktiven Stapel ist das Gegenstück aggrega auth token, das den Browser-OIDC-Ablauf einmal ausführt und das Identitätstoken auf stdout ausgibt, sodass es auf dieselbe Weise exportiert werden kann:
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)Siehe aggrega-auth.md. Beide Wege ermöglichen es einem Stapel von aggrega sign-Aufrufen, eine einzige Identität ohne Browser-Umweg pro Artefakt wiederzuverwenden.
Ziehen Sie --password-stdin gegenüber AGGREGA_REGISTRY_PASSWORD vor. Eine Umgebungsvariable ist für Kindprozesse lesbar und kann in einer Shell bestehen bleiben; stdin ist der sicherere Weg für das Passwort. Die Umgebungsvariable existiert als Erleichterung für CI.
Siehe auch
- configuration.md — in welche Datei eine Einstellung gehört, und das vollständige Rangfolgemodell, in das sich diese Variablen einfügen.
- global-flags.md —
--workspace-rootundAGGREGA_CONFIG. - aggrega-push.md und aggrega-sign.md — Signaturvariablen und der Alias für das Identitätstoken.
- aggrega-auth.md —
aggrega auth token, um das Identitätstoken interaktiv zu beziehen. - aggrega-pull.md und aggrega-build.md — Variablen für Offline, Auto-Pull, Katalogverzeichnisse und Cache.
- ../../architecture/13-catalog-and-registry.md — die Registry- und Signatureinstellungen, die mehrere dieser Variablen übersteuern.