Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

aggrega config

Die Workspace-Konfiguration inspizieren und verwalten

Übersicht

aggrega config

Beschreibung

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.

Unterbefehle

BefehlBeschreibung
aggrega config captureFriert die effektive build-kritische Konfiguration in diesem Workspace ein
aggrega config initLegt eine funktionsfähige Konfiguration mit einer Registry und ihrer Vertrauensrichtlinie an
aggrega config showZeigt die effektive Konfiguration und woher jede Einstellung stammt

Beschreibung von 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.

Flags von aggrega config capture

FlagStandardBeschreibung
--all-pluginsfalseErfasst alle Plugin-Sockets, einschließlich der Governance-Gates mit Verdict-Rolle, der Linter- und der Importer-Gates. Ohne es friert capture nur die Sockets ein, die die gerenderte Ausgabe bestimmen (die Provider-Bindungen und die Governance-Attachments mit Transform-Rolle).

Beschreibung von 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.

Flags von aggrega config init

FlagStandardBeschreibung
--dry-runfalseTut alles außer Schreiben: gibt die angelegte Konfiguration als Inhalt zurück, nennt die Datei, für die sie bestimmt ist, und erstellt oder ändert nichts. Jedes andere Verhalten ist das des Schreibvorgangs, sodass eine vorhandene Konfigurationsdatei genau so abgelehnt wird, wie ein Schreibvorgang sie ablehnt — übergeben Sie zusätzlich —force für die Zusammenführung, die ein überschreibender Schreibvorgang erzeugen würde.
--forcefalseÜberschreibt eine vorhandene Konfigurationsdatei. Ohne es verweigert init, wenn die Zieldatei bereits existiert.
--globalfalseSchreibt den Eintrag in die globale Konfiguration, die von allen Workspaces gemeinsam genutzt wird. Dies ist der Standard.
--registryhub.aggrega.aiRegistry-Host, der mit seiner Vertrauensrichtlinie angelegt werden soll. Standardmäßig der offizielle Hub.
--workspacefalseSchreibt den Eintrag in die Workspace-Konfiguration dieses Projekts statt in die globale Konfiguration.

Beschreibung von 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.

Flags von aggrega config show

FlagStandardBeschreibung
--globalfalseGibt die eigenen Bytes der globalen Konfigurationsdatei unverändert aus, wobei Kommentare und Formatierung erhalten bleiben.
--originfalseVersieht jede effektive Einstellung mit der Ebene, aus der sie stammt (ein Befehlszeilen-Flag, eine Umgebungsvariable, eine Konfigurationsdatei oder die integrierten Standardwerte).
--workspacefalseGibt die eigenen Bytes der Workspace-Konfigurationsdatei dieses Projekts unverändert aus, wobei Kommentare und Formatierung erhalten bleiben.

Funktionsweise

Die config-Unterbefehle legen die Konfiguration an, die einen Build steuert, untersuchen sie und frieren sie ein. Welche Datei eine Einstellung aufnimmt und wie die Ebenen zusammenwirken, erfahren Sie unter Konfiguration — es beginnt mit den beiden Dateien, die die meisten Projekte benötigen, und stellt den Rest dahinter zurück.

config init — eine funktionsfähige Konfiguration anlegen

aggrega config init legt auf einer neuen Maschine eine Konfiguration an, indem es eine Registry und ihre Signatur-Vertrauensrichtlinie registriert, sodass signierte Artefakte ohne manuelles Bearbeiten von YAML abgerufen und verifiziert werden. Standardmäßig registriert es den offiziellen Hub (hub.aggrega.ai) mit erforderlichen Signaturen und seinen offiziellen vertrauenswürdigen Identitäten. Die von der Registry angekündigte Vertrauensrichtlinie wird einmal von ihrem eigenen Ursprung abgerufen und lokal gepinnt (Trust-on-First-Use); wenn der Hub nicht erreichbar ist, nichts ankündigt oder der Workspace offline ist, wird stattdessen seine integrierte offizielle Baseline geschrieben, sodass init auch offline eine nutzbare Konfiguration erzeugt.

Vor allem anderen sagt init, wo sich die Dinge befinden. Das Anlegen auf einer neuen Linux-Maschine beginnt mit:

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

und auf einer neuen Windows-Maschine mit:

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

Die erste Zeile nennt die Konfigurationsdatei, die init geschrieben hat: Created, wenn die Datei nicht vorhanden war, und Using, wenn sie vorhanden war und --force init hineinschreiben ließ; unter --workspace nennt sie die Workspace-Konfigurationsdatei statt der globalen. Die zweite nennt das Verzeichnis, in dem die maschinenweiten Caches — kompilierte Plugins und ihre Beschreibungen — aufbewahrt werden, also dort, wo jede Plattform die Caches eines Benutzers ablegt; Welche Caches zu diesem Projekt gehören und welche zur Maschine gibt die Regel pro Plattform an. Jede Zeile endet mit ihrem Pfad und nichts danach, sodass der Pfad unverändert kopiert werden kann. Die folgenden Zeilen gehören zur Registrierung selbst: was der Abruf der Vertrauensrichtlinie gefunden hat und in welcher Datei die Registry registriert wurde. Ein abgelehntes Anlegen gibt keine der beiden Zeilen aus, da es nichts erstellt hat, und ebenso wenig --dry-run, dessen Standardausgabe nur den zurückgegebenen Inhalt enthält.

  • --registry <host> legt statt der offiziellen eine andere Registry an — einen air-gapped oder privaten Hub. Eine solche Registry hat keine integrierte Baseline, sodass der Eintrag dort, wo sie nichts ankündigt, ohne Richtlinie geschrieben wird, und in einem Offline-Workspace wird das Anlegen abgelehnt (Kurzcode E0310): Die Richtlinie kann nicht abgerufen werden, und init nimmt kein --identity oder --key an, um eine manuell zu pinnen. Legen Sie sie einmal an, während Sie online sind, oder fügen Sie sie mit aggrega registry add und einer von Ihnen bereitgestellten Richtlinie hinzu.
  • Wenn die Zieldatei bereits existiert, verweigert init, statt sie zu überschreiben; --force schreibt trotzdem, führt den Registry-Eintrag in die vorhandene Datei zusammen und behält andere Einstellungen bei.
  • --dry-run tut alles, was init tut, außer Schreiben. Es gibt die angelegte Konfiguration als Inhalt zurück, erstellt und ändert nichts, und die Antwort nennt die Datei, für die der Inhalt bestimmt ist — was hier wichtig ist, weil das Ziel die globale Konfiguration ist, sofern nicht --workspace die dieses Projekts auswählt. Ein Aufrufer, der sein eigenes Dokumentmodell führt, etwa ein Editor, legt den Inhalt dort ab, wo er sichtbar ist, bevor er gespeichert wird, und geändert oder rückgängig gemacht werden kann.
  • Da ein Probelauf alles andere tut, was init tut, sagt sein Exit-Code den des Schreibvorgangs voraus. Er lehnt eine vorhandene Konfigurationsdatei genau so ab, wie ein Schreibvorgang sie ablehnt, und aus demselben Grund, sodass Sie damit fragen können, ob init erfolgreich wäre, bevor Sie sich auf die Änderung festlegen. Um das Dokument zu sehen, das ein überschreibender Schreibvorgang erzeugen würde, übergeben Sie zusätzlich --force: --force --dry-run meldet die Zusammenführung und schreibt weiterhin nichts.
  • Die Registry wird trotzdem nach ihrer angekündigten Vertrauensrichtlinie abgefragt, weil die Richtlinie im gemeldeten Inhalt diejenige ist, die ein Schreibvorgang gepinnt hätte. Ein Probelauf stellt dieselbe einzelne nicht authentifizierte Anfrage an den eigenen Ursprung dieser Registry wie ein Schreibvorgang.
  • Unter --dry-run enthält die Standardausgabe diesen Inhalt und nichts anderes, sodass sie parsebar bleibt. Das Einzige, was der Inhalt nicht ausdrücken kann, ist ein Fehlen: Wenn eine Registry keine Vertrauensrichtlinie ankündigt und ohne eine angelegt wird, geht der Hinweis darauf — der Sie auffordert, Identitäten mit --identity oder --key zu pinnen — an die Standardfehlerausgabe. Ein Konfigurationsdokument ohne vertrauenswürdige Identitäten sieht gleich aus, ob eine Richtlinie gepinnt wurde und zufällig leer war oder überhaupt keine angekündigt wurde; lesen Sie daher beide Streams; ein Programm, das die Standardfehlerausgabe verwirft, erfährt davon nichts. Wenn die Registry eine Richtlinie ankündigt oder an ihrer Stelle die integrierte Baseline des offiziellen Hubs gepinnt wird, steht die gepinnte Richtlinie im gemeldeten Inhalt selbst, und es wird kein separater Hinweis erzeugt.

Eine angelegte Konfiguration ist ein Dokument, das Ihnen gehört und das Sie weiter bearbeiten, weshalb sie zurückgegeben statt geschrieben werden kann. Das Einfrieren der effektiven Konfiguration, siehe unten, erzeugt eine Aufzeichnung dessen, wozu sich die Konfiguration aufgelöst hat — Zustand, den der Compiler über sich selbst führt, statt Inhalt, den jemand verfasst —, daher schreibt es immer und bietet kein --dry-run.

config show — untersuchen, was gerade gilt

aggrega config show meldet die Konfiguration, die gerade gilt. In der Standardansicht beginnt es mit der Kaskade der beteiligten Konfigurationsdateien und Umgebungsüberschreibungen, niedrigste Priorität zuerst, und gibt dann die effektive zusammengeführte Konfiguration aus — die globale Konfiguration, die Kaskade des Workspace-Baums und jede Umgebungsüberlagerung, zu einem einzigen Ergebnis kombiniert. In dieser Kaskade geladener Dateien bestätigen Sie, welche Dateien und Umgebungsüberschreibungen die aktuelle Konfiguration geprägt haben.

Zwei fokussierte Ansichten schränken die Ausgabe ein:

  • --global oder --workspace gibt die eigenen Dateibytes einer einzelnen Ebene unverändert aus, mit erhaltenen Kommentaren und erhaltener Formatierung; wenn die Datei dieser Ebene nicht existiert, sagt es das, statt fehlzuschlagen. Die beiden schließen sich gegenseitig aus.
  • --origin versieht jede effektive Einstellung mit der Ebene, aus der sie stammt — ein Befehlszeilen-Flag, eine Umgebungsvariable, eine Konfigurationsdatei oder die integrierten Standardwerte, höchste Priorität zuerst. Ein Flag wird so genannt, wie Sie es eingegeben haben, sodass eine Einstellung, die --offline bei diesem Lauf bestimmt hat, --offline als Quelle meldet; eine Umgebungsvariable wird hinter einem env:-Präfix genannt und eine Konfigurationsdatei mit ihrem absoluten Pfad.

Unter --origin wird eine Einstellung der Ebene mit der höchsten Priorität zugeschrieben, die sie setzt, unabhängig vom Wert, den diese Ebene schreibt. So wird eine Projektdatei, die default_registry: hub.aggrega.ai schreibt, für diese Einstellung genannt, obwohl der integrierte Standard dieselbe Registry ist, und eine Projektdatei, die einen Wert wiederholt, den die globale Datei bereits setzt, wird statt der globalen Datei genannt: In beiden Fällen ist sie die Datei, die den Wert festhält, und diejenige, deren Entfernung die Antwort an dem Tag ändert, an dem sich der Standard oder die Datei darunter ändert. Eine Einstellung, die keine Ebene setzt, meldet die integrierten Standardwerte.

  • Was als Setzen gilt. Eine Konfigurationsdatei setzt eine Einstellung, wenn sie den Schlüssel dieser Einstellung enthält, und eine Listeneinstellung auch dann, wenn sie das zugehörige _append der Liste enthält. Eine Umgebungsvariable setzt ihre Einstellung, wenn sie mit einem nicht leeren Wert exportiert ist, und ein Flag, wenn Sie es eingeben — --offline=false setzt den Modus ebenso sicher wie --offline.
  • Eine Konfigurationsdatei, die Ihrer Pipeline gehört, wird nur für die Schlüssel genannt, für die sie gelesen wird, nämlich ihre Listenergänzungen und die Signaturrichtlinie. Ein Schlüssel, den sie ignoriert und zu dem sie warnt, wird nie als Herkunft eines Wertes gemeldet.
  • Listen- und Map-Einstellungen werden als Ganzes zugeschrieben, der Ebene mit der höchsten Priorität, die sie setzt; welche Ebene welchen Eintrag einer Liste beigesteuert hat, wird nicht gemeldet.
  • Die Signaturanforderung ist die einzige Ausnahme. Jede Ebene kann sie einschalten und keine kann sie ausschalten, daher nennt sie die erste Ebene, die sie einschaltet. Eine Ebene, die required: false schreibt, schaltet nichts ein, sodass die Einstellung, wenn keine Ebene sie einschaltet, die integrierten Standardwerte meldet.

config capture — build-kritische Einstellungen einfrieren

aggrega config capture schreibt die effektive build-kritische Konfiguration in die Workspace-Konfigurationsdatei dieses Projekts, sodass der Workspace identisch baut, ohne sich auf die globale Konfiguration der Maschine zu stützen. Maschinenweite Tooling-Einstellungen wie die Vertrauensrichtlinie einer Registry werden nicht erfasst; sie bleiben ihrer Natur nach in der globalen Konfiguration. Ein erneuter Aufruf bei unveränderter Konfiguration schreibt dieselbe Datei byteweise identisch neu.

Die erfasste Teilmenge besteht aus einer Menge von Plugin-Socket-Attachments und den Katalogverzeichnissen:

  • Standardmäßig friert capture nur die Sockets ein, die die gerenderte Ausgabe bestimmen — die Provider-Bindungen und die Governance-Attachments mit Transform-Rolle —, da nur diese für bytegleiche Builds mit dem Projekt mitwandern müssen. Die Katalogverzeichnisse werden immer erfasst.
  • --all-plugins erweitert die erfassten Sockets, sodass auch die Governance-Sockets mit Verdict-Rolle sowie die Linter- und Importer-Sockets enthalten sind. Ohne es können diese drei je nach Umgebung frei variieren.

Capture schreibt immer und bietet keine Möglichkeit, stattdessen den Inhalt zurückzuerhalten. Was es erzeugt, ist eine Aufzeichnung dessen, wozu sich die Konfiguration aufgelöst hat, kein Dokument, das jemand verfasst; daher gibt es für einen Autor nichts zu prüfen und zu ändern — es zu melden würde dazu einladen, einen Schnappschuss einer Auflösung zu bearbeiten.

Das Erfassen schreibt nur in einen Workspace. In einem Ordner ausgeführt, der in keinem liegt, ohne dass --workspace-root oder AGGREGA_WORKSPACE_ROOT einen nennt, schreibt es nichts — eine dort geschriebene Konfigurationsdatei würde den Ordner zu einem Workspace machen — und beendet sich mit einem Fehler, der dies angibt. aggrega config init --workspace macht den Ordner zuerst zu einem Workspace.

Siehe auch

  • configuration.md — welche Datei eine Einstellung aufnimmt, die Prioritätsleiter und die Mechanismen, zu denen ein größeres Projekt greift.
  • global-flags.md — die Flags --config und --workspace-root.
  • environment-variables.md — die AGGREGA_*-Variablen, die die Konfiguration zur Laufzeit überschreiben.
  • aggrega-registry.md — Registries und ihre Vertrauensrichtlinie direkt verwalten.
  • aggrega-cache.md — was das Verzeichnis, das artifact_cache_dir nennt, tatsächlich enthält, und warum eine dort liegende Entität, die keine Lockfile pinnt, von einem Build nicht gefunden wird.