Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

aggrega config

Przegląda konfigurację obszaru roboczego i zarządza nią

Składnia

aggrega config

Opis

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.

Podpolecenia

PolecenieOpis
aggrega config captureZamraża w tym obszarze roboczym efektywną konfigurację krytyczną dla kompilacji
aggrega config initTworzy początkową konfigurację roboczą z rejestrem i jego polityką zaufania
aggrega config showPokazuje efektywną konfigurację i źródło każdego ustawienia

Opis 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.

Flagi aggrega config capture

FlagaDomyślnieOpis
--all-pluginsfalsePrzechwytuje wszystkie gniazda pluginów, w tym bramki governance w roli werdyktu, lintera i importera. Bez tej flagi capture zamraża tylko gniazda, które determinują renderowany wynik (powiązania providerów i dołączenia governance w roli transformacji).

Opis 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.

Flagi aggrega config init

FlagaDomyślnieOpis
--dry-runfalseWykonuje wszystko poza zapisem: zwraca utworzoną konfigurację jako treść, wskazując plik, którego dotyczy, i niczego nie tworzy ani nie modyfikuje. Każde inne zachowanie jest takie samo jak przy zapisie, więc istniejący plik konfiguracyjny zostaje odrzucony dokładnie tak, jak odrzuca go zapis — aby otrzymać scalenie, które dałby zapis nadpisujący, należy przekazać razem z nią —force.
--forcefalseNadpisuje istniejący plik konfiguracyjny. Bez tej flagi init odmawia, gdy plik docelowy już istnieje.
--globalfalseZapisuje wpis w globalnej konfiguracji współdzielonej przez wszystkie obszary robocze. Jest to ustawienie domyślne.
--registryhub.aggrega.aiHost rejestru do zarejestrowania wraz z jego polityką zaufania. Domyślnie oficjalny hub.
--workspacefalseZapisuje wpis w konfiguracji obszaru roboczego tego projektu zamiast w konfiguracji globalnej.

Opis 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.

Flagi aggrega config show

FlagaDomyślnieOpis
--globalfalseWypisuje dosłownie bajty globalnego pliku konfiguracyjnego, zachowując jego komentarze i formatowanie.
--originfalseOpisuje każde efektywne ustawienie warstwą, z której pochodzi (flaga wiersza poleceń, zmienna środowiskowa, plik konfiguracyjny lub wbudowane wartości domyślne).
--workspacefalseWypisuje dosłownie bajty pliku konfiguracyjnego obszaru roboczego tego projektu, zachowując jego komentarze i formatowanie.

Działanie

Podpolecenia config inicjują, przeglądają i zamrażają konfigurację, która steruje kompilacją. Informacje o tym, w którym pliku powinno znaleźć się dane ustawienie i jak łączą się warstwy, zawiera strona Konfiguracja — zaczyna od dwóch plików potrzebnych większości projektów, a resztę zostawia na dalszą część.

config init — inicjowanie działającej konfiguracji

aggrega config init tworzy konfigurację na nowej maszynie, rejestrując rejestr i jego politykę zaufania do podpisów, dzięki czemu podpisane artefakty są pobierane i weryfikowane bez ręcznej edycji YAML. Domyślnie rejestruje oficjalny hub (hub.aggrega.ai) z wymaganymi podpisami i jego oficjalnymi zaufanymi tożsamościami. Polityka zaufania ogłaszana przez rejestr jest pobierana jednorazowo z jego własnego źródła i przypinana lokalnie (zaufanie przy pierwszym użyciu); gdy hub jest nieosiągalny, niczego nie ogłasza lub obszar roboczy działa offline, zapisywana jest zamiast niej wbudowana oficjalna konfiguracja bazowa, więc init nadal tworzy użyteczną konfigurację offline.

Przede wszystkim init informuje, gdzie co się znajduje. Inicjowanie nowej maszyny z systemem Linux zaczyna się od:

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

a nowej maszyny z systemem Windows od:

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

Pierwszy wiersz podaje plik konfiguracyjny zapisany przez init: Created, gdy pliku nie było, oraz Using, gdy istniał, a --force pozwoliło init do niego zapisać; przy --workspace podaje plik konfiguracyjny obszaru roboczego zamiast globalnego. Drugi podaje katalog, w którym przechowywane są pamięci podręczne całej maszyny — skompilowane wtyczki i ich opisy — czyli miejsce, w którym dana platforma przechowuje pamięci podręczne użytkownika; regułę dla każdej platformy podaje sekcja Które pamięci podręczne należą do tego projektu, a które do maszyny. Każdy wiersz kończy się ścieżką, po której nic już nie ma, więc ścieżkę można skopiować bez zmian. Kolejne wiersze dotyczą samej rejestracji: co znalazło pobieranie polityki zaufania i w którym pliku zarejestrowano rejestr. Odrzucone inicjowanie nie wypisuje żadnego z tych wierszy, ponieważ niczego nie utworzyło; nie wypisuje ich też --dry-run, którego standardowe wyjście zawiera wyłącznie zwracaną treść.

  • --registry <host> inicjuje inny rejestr — odizolowany od sieci lub prywatny hub — zamiast oficjalnego. Taki rejestr nie ma wbudowanej konfiguracji bazowej, więc gdy niczego nie ogłasza, wpis jest zapisywany bez polityki, a w obszarze roboczym offline jego inicjowanie jest odrzucane (kod skrócony E0310): polityki nie można pobrać, a init nie przyjmuje --identity ani --key, by przypiąć ją ręcznie. Należy zainicjować go raz w trybie online albo dodać go za pomocą aggrega registry add z własną polityką.
  • Jeśli plik docelowy już istnieje, init odmawia zamiast go nadpisać; --force mimo to zapisuje, scalając wpis rejestru z istniejącym plikiem i zachowując pozostałe ustawienia.
  • --dry-run wykonuje wszystko, co robi init, z wyjątkiem zapisu. Zwraca zainicjowaną konfigurację jako treść, niczego nie tworząc ani nie modyfikując, a odpowiedź podaje plik, dla którego treść jest przeznaczona — co ma tu znaczenie, ponieważ celem jest konfiguracja globalna, chyba że --workspace wybierze własną konfigurację tego projektu. Wywołujący, który utrzymuje własny model dokumentu, na przykład edytor, umieszcza tam treść, gdzie jest ona widoczna przed zapisaniem i można ją poprawić lub cofnąć.
  • Ponieważ przebieg próbny robi wszystko inne, co robi init, jego kod wyjścia przewiduje kod wyjścia zapisu. Odrzuca istniejący plik konfiguracyjny dokładnie tak, jak odrzuca go zapis, i z tego samego powodu, więc można go użyć, by sprawdzić, czy init się powiedzie, zanim wprowadzi się zmianę. Aby zobaczyć dokument, który utworzyłby zapis nadpisujący, należy przekazać razem z nim --force: --force --dry-run zgłasza wynik scalenia i nadal niczego nie zapisuje.
  • Rejestr nadal jest odpytywany o ogłaszaną politykę zaufania, ponieważ polityka w zgłaszanej treści jest tą, którą przypiąłby zapis. Przebieg próbny wysyła do własnego źródła tego rejestru to samo pojedyncze nieuwierzytelnione żądanie, które wysyła zapis.
  • Przy --dry-run standardowe wyjście zawiera tę treść i nic więcej, dzięki czemu pozostaje możliwe do sparsowania. Jedyną rzeczą, której treść nie może wyrazić, jest brak: gdy rejestr nie ogłasza polityki zaufania i jest inicjowany bez niej, komunikat o tym — wraz z poleceniem przypięcia tożsamości za pomocą --identity lub --key — trafia na standardowe wyjście błędów. Dokument konfiguracji bez zaufanych tożsamości wygląda tak samo niezależnie od tego, czy przypięto politykę, która okazała się pusta, czy żadna nie została ogłoszona, dlatego należy czytać oba strumienie; program, który odrzuca standardowe wyjście błędów, nie otrzyma o tym żadnej informacji. Gdy rejestr ogłasza politykę lub w jej miejsce przypinana jest wbudowana konfiguracja bazowa oficjalnego hubu, przypięta polityka znajduje się w samej zgłaszanej treści i osobny komunikat nie jest generowany.

Zainicjowana konfiguracja jest dokumentem, którego właścicielem jest użytkownik i który dalej edytuje, dlatego można ją zwrócić zamiast zapisać. Zamrożenie efektywnej konfiguracji, opisane niżej, tworzy zapis tego, do czego konfiguracja się rozwiązała — stan, który kompilator przechowuje o sobie, a nie treść, którą ktoś tworzy — więc zawsze zapisuje i nie oferuje --dry-run.

config show — przegląd tego, co obowiązuje w tej chwili

aggrega config show zgłasza konfigurację obowiązującą w tej chwili. W widoku domyślnym zaczyna od kaskady plików konfiguracyjnych i nadpisań ze zmiennych środowiskowych, które się do niej przyczyniły, od najniższego priorytetu, a następnie wypisuje efektywną scaloną konfigurację — konfigurację globalną, kaskadę drzewa obszaru roboczego i ewentualną nakładkę środowiskową połączone w jeden wynik. W tej kaskadzie wczytanych plików można potwierdzić, które pliki i nadpisania środowiskowe ukształtowały bieżącą konfigurację.

Dwa ukierunkowane widoki zawężają wyjście:

  • --global lub --workspace wypisuje dosłownie bajty pliku pojedynczej warstwy, z zachowaniem komentarzy i formatowania; gdy plik tej warstwy nie istnieje, informuje o tym zamiast zakończyć się błędem. Te dwie opcje wzajemnie się wykluczają.
  • --origin opisuje każde efektywne ustawienie warstwą, z której pochodzi — flagą wiersza poleceń, zmienną środowiskową, plikiem konfiguracyjnym lub wbudowanymi wartościami domyślnymi, od najwyższego priorytetu. Flaga jest podawana tak, jak ją wpisano, więc ustawienie określone w tym uruchomieniu przez --offline podaje --offline jako swoje źródło; zmienna środowiskowa jest podawana z prefiksem env:, a plik konfiguracyjny przez swoją ścieżkę bezwzględną.

Przy --origin ustawienie jest przypisywane warstwie o najwyższym priorytecie, która je ustawia, niezależnie od zapisanej przez nią wartości. Dlatego plik projektu zawierający default_registry: hub.aggrega.ai jest podawany dla tego ustawienia, mimo że wbudowana wartość domyślna to ten sam rejestr, a plik projektu powtarzający wartość ustawioną już przez plik globalny jest podawany zamiast pliku globalnego: w obu przypadkach to on utrzymuje wartość i to jego usunięcie zmieni odpowiedź w dniu, w którym zmieni się wartość domyślna lub plik pod nim. Ustawienie, którego nie ustawia żadna warstwa, podaje wbudowane wartości domyślne.

  • Co oznacza ustawienie. Plik konfiguracyjny ustawia ustawienie, gdy zawiera jego klucz, a w przypadku ustawienia listowego także wtedy, gdy zawiera towarzyszący liście klucz _append. Zmienna środowiskowa ustawia swoje ustawienie, gdy jest wyeksportowana z niepustą wartością, a flaga — gdy zostanie wpisana: --offline=false ustawia tryb tak samo jak --offline.
  • Plik konfiguracyjny należący do potoku jest podawany tylko dla kluczy, dla których jest odczytywany, czyli jego dodatków do list i polityki podpisywania. Klucz, który ignoruje i o którym ostrzega, nigdy nie jest zgłaszany jako źródło wartości.
  • Ustawienia listowe i mapowe są przypisywane w całości warstwie o najwyższym priorytecie, która je ustawia; nie jest zgłaszane, która warstwa dodała który element listy.
  • Jedynym wyjątkiem jest wymóg podpisywania. Każda warstwa może go włączyć, a żadna nie może go wyłączyć, więc podawana jest pierwsza warstwa, która go włącza. Warstwa zapisująca required: false niczego nie włącza, więc gdy żadna warstwa go nie włącza, ustawienie podaje wbudowane wartości domyślne.

config capture — zamrożenie ustawień krytycznych dla budowania

aggrega config capture zapisuje efektywną konfigurację krytyczną dla budowania do pliku konfiguracji przestrzeni roboczej tego projektu, dzięki czemu przestrzeń robocza buduje się identycznie bez polegania na globalnej konfiguracji maszyny. Ustawienia narzędzi obowiązujące w całej maszynie, takie jak polityka zaufania rejestru, nie są przechwytywane; z natury pozostają w konfiguracji globalnej. Ponowne uruchomienie przy niezmienionej konfiguracji zapisuje ten sam plik bajt w bajt.

Przechwytywany podzbiór to zestaw podłączeń do gniazd pluginów oraz katalogi katalogów encji:

  • Domyślnie przechwytywanie zamraża tylko gniazda, które określają renderowany wynik — powiązania dostawców oraz podłączenia governance w roli transformacji — ponieważ tylko one muszą podróżować razem z projektem, aby budowania były identyczne bajt w bajt. Katalogi katalogów encji są przechwytywane zawsze.
  • --all-plugins rozszerza przechwytywane gniazda o gniazda governance w roli werdyktu, linterów i importerów. Bez tej flagi te trzy mogą się swobodnie różnić w zależności od środowiska.

Przechwytywanie zawsze zapisuje i nie oferuje możliwości otrzymania treści zamiast zapisu. To, co tworzy, jest zapisem tego, do czego rozwiązała się konfiguracja, a nie dokumentem, który ktoś komponuje, więc autor nie ma czego przeglądać ani poprawiać — zwrócenie go zachęcałoby do edytowania migawki rozwiązania.

Przechwytywanie zapisuje wyłącznie w obszarze roboczym. Uruchomione w folderze, który nie leży w żadnym obszarze roboczym, gdy żadnego nie wskazuje --workspace-root ani AGGREGA_WORKSPACE_ROOT, niczego nie zapisuje — zapisany tam plik konfiguracyjny zamieniłby folder w obszar roboczy — i kończy działanie z błędem, który o tym informuje. aggrega config init --workspace najpierw czyni folder obszarem roboczym.

Zobacz także

  • configuration.md — w którym pliku należy umieścić dane ustawienie, hierarchia pierwszeństwa oraz mechanizmy, po które sięga większy projekt.
  • global-flags.md — flagi --config i --workspace-root.
  • environment-variables.md — zmienne AGGREGA_*, które nadpisują konfigurację w czasie działania.
  • aggrega-registry.md — bezpośrednie zarządzanie rejestrami i ich polityką zaufania.
  • aggrega-cache.md — co faktycznie zawiera katalog wskazywany przez artifact_cache_dir i dlaczego kompilacja nie znajduje znajdującej się tam encji, której nie przypina żaden plik blokady.