Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

aggrega config

Переглядати й керувати конфігурацією робочого простору

Синтаксис

aggrega config

Опис

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.

Підкоманди

КомандаОпис
aggrega config captureЗафіксувати чинну критичну для збирання конфігурацію в цьому робочому просторі
aggrega config initСтворити робочу конфігурацію з реєстром і його політикою довіри
aggrega config showПоказати чинну конфігурацію і джерело кожного параметра

Опис 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.

Прапорці aggrega config capture

ПрапорецьЗа замовчуваннямОпис
--all-pluginsfalseЗафіксувати всі сокети плагінів, зокрема шлюзи governance з роллю verdict, лінтера та імпортера. Без цього прапорця capture фіксує лише сокети, що визначають згенерований результат (прив’язки провайдерів і приєднання governance з роллю transform).

Опис 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.

Прапорці aggrega config init

ПрапорецьЗа замовчуваннямОпис
--dry-runfalseВиконати все, крім запису: повернути створену конфігурацію як вміст, назвавши файл, для якого вона призначена, і нічого не створювати й не змінювати. Решта поведінки така сама, як під час запису, тож наявний файл конфігурації відхиляється так само, як його відхиляє запис, — передайте разом із ним —force, щоб отримати результат злиття, який дав би запис із перезаписом.
--forcefalseПерезаписати наявний файл конфігурації. Без цього прапорця init відмовляє, якщо цільовий файл уже існує.
--globalfalseЗаписати запис у глобальну конфігурацію, спільну для всіх робочих просторів. Це типова поведінка.
--registryhub.aggrega.aiХост реєстру, який слід додати з його політикою довіри. Типово — офіційний хаб.
--workspacefalseЗаписати запис у конфігурацію робочого простору цього проєкту замість глобальної конфігурації.

Опис 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.

Прапорці aggrega config show

ПрапорецьЗа замовчуваннямОпис
--globalfalseВивести власні байти глобального файлу конфігурації дослівно, зберігаючи його коментарі та форматування.
--originfalseПозначити кожен чинний параметр шаром, з якого він походить (прапорець командного рядка, змінна середовища, файл конфігурації або вбудовані типові значення).
--workspacefalseВивести власні байти файлу конфігурації робочого простору цього проєкту дослівно, зберігаючи його коментарі та форматування.

Що вона робить

Підкоманди config створюють початкову конфігурацію, переглядають і фіксують конфігурацію, що керує збіркою. Про те, до якого файлу належить налаштування і як поєднуються шари, див. Конфігурація — розділ починається з двох файлів, потрібних більшості проєктів, а решту залишає на потім.

config init — створення робочої конфігурації

aggrega config init створює конфігурацію на новій машині, реєструючи реєстр і його політику довіри до підписів, щоб підписані артефакти завантажувалися й перевірялися без ручного редагування YAML. За замовчуванням реєструється офіційний хаб (hub.aggrega.ai) з обов’язковими підписами та його офіційними довіреними ідентичностями. Оголошену реєстром політику довіри одноразово отримують з його власного джерела й закріплюють локально (довіра при першому використанні); якщо хаб недоступний, нічого не оголошує або робочий простір працює офлайн, замість неї записується вбудована офіційна базова політика, тож init і офлайн створює придатну конфігурацію.

Насамперед init повідомляє, де що розташовано. На новій машині з Linux виведення починається так:

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

а на новій машині з Windows так:

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

Перший рядок називає файл конфігурації, який записала команда init: Created, якщо файлу не було, і Using, якщо він був і --force дозволив init записати в нього; з --workspace називається файл конфігурації робочого простору замість глобального. Другий називає каталог, у якому зберігаються кеші всієї машини — скомпільовані плагіни та їхні описи; це місце, де кожна платформа зберігає кеші користувача; Які кеші належать цьому проєкту, а які — машині наводить правило для кожної платформи. Кожен рядок закінчується шляхом, після якого нічого немає, тож шлях можна скопіювати як є. Наступні рядки стосуються самої реєстрації: що знайшов запит політики довіри і в якому файлі зареєстровано реєстр. Відхилене створення не виводить жодного з цих рядків, бо нічого не створило, як і --dry-run, стандартне виведення якого містить лише повернений вміст.

  • --registry <host> замість офіційного реєстру реєструє інший — ізольований або приватний хаб. Такий реєстр не має вбудованої базової політики, тож якщо він нічого не оголошує, запис створюється без політики, а в офлайн-робочому просторі його створення відхиляється (короткий код E0310): політику неможливо отримати, а init не приймає --identity чи --key, щоб закріпити її вручну. Виконайте створення один раз онлайн або додайте реєстр за допомогою aggrega registry add з політикою, яку ви надаєте.
  • Якщо цільовий файл уже існує, init відмовляється його перезаписувати; --force усе одно записує, об’єднуючи запис реєстру з наявним файлом і зберігаючи інші налаштування.
  • --dry-run робить усе, що робить init, крім запису. Він повертає створену конфігурацію як вміст, нічого не створюючи й не змінюючи, а відповідь називає файл, для якого призначено вміст, — це важливо, бо цільовим є глобальний конфіг, якщо --workspace не вибирає власний конфіг цього проєкту. Викликач, що має власну модель документа, як-от редактор, поміщає вміст туди, де його видно до збереження і де його можна змінити або скасувати.
  • Оскільки пробний запуск робить усе інше, що робить init, його код виходу передбачає код виходу запису. Він відхиляє наявний файл конфігурації точно так, як запис, і з тієї самої причини, тож ним можна перевірити, чи init завершиться успішно, перш ніж вносити зміну. Щоб побачити документ, який створив би перезапис, передайте разом із ним --force: --force --dry-run показує результат об’єднання і все одно нічого не записує.
  • До реєстру все одно звертаються по його оголошену політику довіри, бо політика у звітному вмісті — це політика, яку закріпив би запис. Пробний запуск робить той самий єдиний неавтентифікований запит до власного джерела реєстру, що й запис.
  • З --dry-run стандартне виведення містить цей вміст і нічого іншого, тож воно залишається придатним для розбору. Єдине, чого вміст не може виразити, — це відсутність: коли реєстр не оголошує політики довіри й реєструється без неї, повідомлення про це — разом із порадою закріпити ідентичності через --identity або --key — надходить у стандартний потік помилок. Документ конфігурації без довірених ідентичностей виглядає однаково, чи то політику закріплено й вона виявилася порожньою, чи то її взагалі не оголошено, тож читайте обидва потоки; програма, що відкидає стандартний потік помилок, нічого про це не дізнається. Коли реєстр оголошує політику або замість неї закріплюється вбудована базова політика офіційного хабу, закріплена політика міститься в самому звітному вмісті, і окреме повідомлення не виводиться.

Створена конфігурація — це документ, яким ви володієте й надалі редагуєте, тому її можна повернути, а не записати. Фіксація ефективної конфігурації, описана нижче, створює запис того, у що розв’язалася конфігурація, — стан, який компілятор зберігає про себе, а не вміст, який хтось складає, — тож вона завжди записує й не пропонує --dry-run.

config show — перегляд того, що діє зараз

aggrega config show показує конфігурацію, що діє зараз. У поданні за замовчуванням спершу виводиться каскад файлів конфігурації та перевизначень із середовища, які зробили внесок, від найнижчого пріоритету, а потім ефективна об’єднана конфігурація — глобальний конфіг, каскад дерева робочого простору й будь-яке накладання середовища, поєднані в один результат. Саме в цьому каскаді завантажених файлів можна переконатися, які файли й перевизначення із середовища сформували поточну конфігурацію.

Два вузькі подання звужують виведення:

  • --global або --workspace дослівно виводить байти власного файлу одного шару зі збереженням коментарів і форматування; якщо файлу цього шару немає, команда повідомляє про це, а не завершується з помилкою. Ці два прапорці взаємовиключні.
  • --origin позначає кожне ефективне налаштування шаром, з якого воно походить, — прапорець командного рядка, змінна середовища, файл конфігурації або вбудовані значення за замовчуванням, від найвищого пріоритету. Прапорець називається так, як ви його ввели, тож налаштування, яке визначив --offline у цьому запуску, показує --offline як джерело; змінна середовища називається з префіксом env:, а файл конфігурації — за абсолютним шляхом.

З --origin налаштування приписується шару з найвищим пріоритетом, який його задає, незалежно від значення, яке цей шар записує. Тож файл проєкту, що записує default_registry: hub.aggrega.ai, називається для цього налаштування, хоча вбудоване значення за замовчуванням — той самий реєстр, а файл проєкту, що повторює значення, вже задане глобальним файлом, називається замість глобального файлу: в обох випадках саме цей файл утримує значення, і саме його видалення змінить відповідь того дня, коли значення за замовчуванням або файл під ним зміниться. Налаштування, яке не задає жоден шар, показує вбудовані значення за замовчуванням.

  • Що вважається заданням налаштування. Файл конфігурації задає налаштування, коли містить його ключ, а налаштування-список — також коли містить супутній ключ _append цього списку. Змінна середовища задає своє налаштування, коли її експортовано з непорожнім значенням, а прапорець — коли ви його вводите: --offline=false задає режим так само, як --offline.
  • Файл конфігурації, яким володіє ваш конвеєр, називається лише для ключів, заради яких його читають, — це його доповнення списків і політика підписування. Ключ, який він ігнорує й про який попереджає, ніколи не вказується як джерело значення.
  • Налаштування-списки й налаштування-словники приписуються цілком шару з найвищим пріоритетом, який їх задає; який шар додав який елемент списку, не показується.
  • Єдиний виняток — вимога підписування. Будь-який шар може її ввімкнути, і жоден не може вимкнути, тож вказується перший шар, що її вмикає. Шар, який записує required: false, нічого не вмикає, тож якщо жоден шар її не вмикає, налаштування показує вбудовані значення за замовчуванням.

config capture — зафіксувати налаштування, критичні для збирання

aggrega config capture записує чинну конфігурацію, критичну для збирання, у файл конфігурації робочого простору цього проєкту, щоб робочий простір збирався однаково, не покладаючись на глобальну конфігурацію машини. Загальномашинні налаштування інструментів, як-от політика довіри реєстру, не фіксуються: за своєю природою вони залишаються в глобальній конфігурації. Повторний запуск на незмінній конфігурації перезаписує той самий файл байт у байт.

Зафіксована підмножина — це набір приєднань до сокетів плагінів і каталоги каталогів сутностей:

  • Типово фіксуються лише сокети, що визначають результат рендерингу, — прив’язки провайдерів і приєднання керування в ролі перетворення, — оскільки лише вони мають переноситися разом із проєктом для побайтово ідентичних збирань. Каталоги каталогів сутностей фіксуються завжди.
  • --all-plugins розширює зафіксовані сокети, додаючи також сокети керування в ролі вердикту, лінтерів та імпортерів. Без нього ці три можуть вільно відрізнятися залежно від середовища.

Фіксація завжди записує файл і не пропонує способу натомість отримати вміст. Те, що вона створює, — це запис того, до чого розв’язалася конфігурація, а не документ, який хтось складає, тож авторові нема чого переглядати й змінювати: повернення вмісту спонукало б редагувати знімок результату розв’язання.

Захоплення записує лише в робочий простір. Запущене в теці, яка не перебуває в жодному робочому просторі, коли ні --workspace-root, ні AGGREGA_WORKSPACE_ROOT не називає жодного, воно нічого не записує — файл конфігурації, записаний там, перетворив би теку на робочий простір — і завершується з помилкою, яка про це повідомляє. aggrega config init --workspace спершу робить теку робочим простором.

Див. також

  • configuration.md — до якого файлу належить параметр, драбина пріоритетів і механізми, до яких вдається більший проєкт.
  • global-flags.md — прапорці --config і --workspace-root.
  • environment-variables.md — змінні AGGREGA_*, що перевизначають конфігурацію під час виконання.
  • aggrega-registry.md — безпосереднє керування реєстрами та їхньою політикою довіри.
  • aggrega-cache.md — що насправді містить каталог, який задає artifact_cache_dir, і чому збірка не знаходить сутність, що лежить там, але не закріплена жодним lock-файлом.