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 catalogdirectories, its provider bindings, which lint rules it relaxes. It iscommitted, 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 thedirectory the APPDATA environment variable names. It holds what belongs to themachine rather than to any one project: the registries you pull from and thesignature trust policy for each, how large the compiled-module store may grow,any command extension you have installed. It loads automatically when it isthere, and nothing breaks when it is not.
Your project's file wins over the global one, an environment variable winsover both, and a flag wins over everything.
Secrets are not configuration. A registry password or a signing identity tokenis never a field in either file; it is supplied by environment variable or flagat 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 howyou find out which layer each setting came from. "aggrega config init" seeds aworking configuration, and "aggrega config capture" freezes the effectivebuild-critical settings into this workspace so a build does not depend on aglobal file that is not committed.
Larger projects have more to work with. None of it is needed to start, and eachpiece 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 workspaceconfig file, so the workspace builds identically without relying on themachine's global configuration.
The build-critical subset is the configuration a build participates in: a set ofplugin socket attachments and the catalog directories. By default the capturedsockets are only those that determine therendered output — the provider bindings and the transform-role governance attachments — since only those musttravel with the project for byte-identical output. Pass --all-plugins to alsofreeze the verdict-role governance, linter, and importer sockets, which otherwise stay free tovary by environment. Each field is written at its effective value — the valuethat resolves right now with the global configuration and the workspace treemerged together — so a binding that today comes only from the global config ismaterialized into the workspace and travels with the project.
Machine-wide tooling settings, such as a registry's trust policy, are notcaptured: they stay in the global config by their nature. Capture always writesthis project's workspace config file. Running it again on an unchangedconfiguration rewrites the same file byte-for-byte. Run in a folder that is notinside a workspace, with no --workspace-root naming one, it writes nothing andexits with an error saying so.aggrega config capture のフラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--all-plugins | false | 判定ロールのガバナンス、リンター、インポーターのゲートを含む、すべてのプラグインソケットを固定します。指定しない場合、capture はレンダリング結果を決定するソケット(プロバイダーのバインディングと変換ロールのガバナンスのアタッチメント)のみを固定します。 |
aggrega config init の説明
Seed a working configuration by registering a registry and its signature trustpolicy, so a fresh machine can pull and verify signed artifacts without editingYAML by hand.
By default it registers the official hub (hub.aggrega.ai) with signaturesrequired and the official trusted identities. The registry's advertised trustpolicy is fetched once from its own origin and pinned locally — trust-on-first-use; when the hub is unreachable, advertises nothing, or the workspace isoffline, its built-in official baseline is written instead, so init stillproduces 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 noidentities or key to pin by hand, so register it once while online, or add itwith "aggrega registry add --identity" or "--key".
The entry is written to the global config shared across every workspace bydefault; pass --workspace to write it to this project's workspace configinstead. If the target config file already exists, init refuses rather thanoverwrite it — pass --force to write anyway (the registry entry is merged intothe existing file, other settings preserved).
Before anything else, init says where things are: the configuration file itcreated — or, under --force, the one already there that it wrote into — andthe directory the machine-wide caches are kept in. On Windows that directory isaggrega\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 doeseverything init does except write: it hands the content back, creating andmodifying nothing. The answer names the file the content is for — which mattershere, because the target is the global config unless --workspace selects thisproject'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 registryis still contacted for its advertised trust policy, because the policy in thatcontent is the policy a write would have pinned.
Because a dry run does everything else init does, it refuses an existing configfile exactly as a write refuses it, and for the same reason. So its exit codepredicts 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 staysparseable. A registry seeded with no trust policy, because it advertises none,still produces its notice, on standard error: read that stream too, or thatconfiguration arrives without the advice to pin identities by hand. A pinnedpolicy, whether advertised or the hub's built-in baseline, is in the contentitself and produces no notice.aggrega config init のフラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--dry-run | false | 書き込み以外のすべてを行います。初期化された設定を、対象となるファイル名とともに内容として返し、何も作成・変更しません。その他の動作はすべて書き込み時と同じであるため、既存の設定ファイルは書き込み時とまったく同じように拒否されます。上書きする書き込みが生成するマージ結果を得るには、—force を併せて指定します。 |
--force | false | 既存の設定ファイルを上書きします。指定しない場合、対象ファイルがすでに存在すると init は拒否します。 |
--global | false | すべてのワークスペースで共有されるグローバル設定にエントリーを書き込みます。これがデフォルトです。 |
--registry | hub.aggrega.ai | 信頼ポリシーとともに初期化するレジストリホスト。デフォルトは公式ハブです。 |
--workspace | false | グローバル設定の代わりに、このプロジェクトのワークスペース設定にエントリーを書き込みます。 |
aggrega config show の説明
Show the configuration that applies right now.
By default it leads with the cascade of config files and environment overridesthat contributed, lowest precedence first, then prints the effective mergedconfiguration — the global config, the workspace-tree cascade, and anyenvironment 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 itsays 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-indefaults, highest precedence first. A flag is named as the reader typed it, soa setting a flag decided reports that flag as its source. A setting isattributed to the highest-precedence layer that sets it, whatever value thatlayer writes: a file restating the default is the file named, not the built-indefaults. List and map settings are attributed as a whole. The signingrequirement is the one exception: any layer may turn it on and none can turn itoff, so it names the first layer that turns it on.aggrega config show のフラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--global | false | グローバル設定ファイル自体のバイト列を、コメントと書式を保持したままそのまま出力します。 |
--origin | false | 有効な各設定項目に、その由来となったレイヤー(コマンドラインフラグ、環境変数、設定ファイル、または組み込みのデフォルト)を注記します。 |
--workspace | false | このプロジェクトのワークスペース設定ファイル自体のバイト列を、コメントと書式を保持したままそのまま出力します。 |
動作
config サブコマンドは、ビルドを制御する設定のシード、確認、固定を行います。どの設定をどのファイルに置くか、またレイヤーがどのように組み合わされるかについては、設定を参照してください。このページは、ほとんどのプロジェクトに必要な 2 つのファイルから説明を始め、それ以外はその後に回しています。
config init — 動作する設定をシードする
aggrega config init は、レジストリとその署名トラストポリシーを登録することで新しいマシン上に設定をシードし、YAML を手で編集しなくても署名済みアーティファクトを取得して検証できるようにします。デフォルトでは、署名を必須とし、公式の信頼済みアイデンティティを持つ公式ハブ (hub.aggrega.ai) を登録します。レジストリが公開するトラストポリシーは、そのレジストリ自身のオリジンから一度だけ取得され、ローカルに固定されます (trust-on-first-use)。ハブに到達できない場合、ハブが何も公開していない場合、またはワークスペースがオフラインの場合は、代わりに組み込みの公式ベースラインが書き込まれるため、init はオフラインでも使用可能な設定を生成します。
init は、何よりも先に、各ファイルの場所を示します。新しい Linux マシンへのシードは次の出力で始まります。
Created the global configuration file at /home/you/.config/aggrega/config.yamlMachine-wide caches are kept in /home/you/.cache/aggrega新しい Windows マシンでは次のとおりです。
Created the global configuration file at C:\Users\you\AppData\Roaming\aggrega\config.yamlMachine-wide caches are kept in C:\Users\you\AppData\Local\aggrega\cache1 行目は init が書き込んだ設定ファイルを示します。ファイルが存在しなかった場合は Created、存在していて --force により init がそこに書き込んだ場合は Using です。--workspace を指定した場合は、グローバル設定ファイルではなくワークスペース設定ファイルを示します。2 行目は、マシン全体のキャッシュ (コンパイル済みプラグインとその記述) が置かれるディレクトリを示します。これは各プラットフォームがユーザーのキャッシュを置く場所です。プラットフォームごとの規則はWhich caches belong to this project, and which to the machineを参照してください。各行はパスで終わり、その後には何も続かないため、パスをそのままコピーできます。その後に続く行は登録処理自体の出力で、トラストポリシーの取得で何が見つかったか、およびレジストリがどのファイルに登録されたかを示します。拒否されたシードは何も作成していないため、どちらの行も出力しません。--dry-run も同様で、その標準出力には返されるコンテンツのみが含まれます。
--registry <host>は、公式ハブの代わりに別のレジストリ (エアギャップ環境やプライベートのハブ) をシードします。このようなレジストリには組み込みのベースラインがないため、何も公開されていない場合はポリシーなしでエントリが書き込まれ、オフラインのワークスペースではシードが拒否されます (短縮コードE0310)。ポリシーを取得できず、initには手動でポリシーを固定するための--identityや--keyがないためです。オンラインのときに一度シードするか、aggrega registry addと自分で用意したポリシーを使って追加してください。- 対象ファイルがすでに存在する場合、
initは上書きせずに拒否します。--forceを指定すると書き込みを行い、レジストリのエントリを既存のファイルにマージして、他の設定は保持します。 --dry-runは、書き込み以外はinitと同じ処理をすべて行います。シードされた設定をコンテンツとして返し、何も作成・変更しません。応答には、そのコンテンツがどのファイル向けかが示されます。--workspaceでこのプロジェクト自身の設定を選択しない限り対象はグローバル設定であるため、これは重要です。エディターのように独自のドキュメントモデルを持つ呼び出し元は、そのコンテンツを自身のモデルに配置します。そこでは保存前に内容を確認でき、修正や取り消しも可能です。- ドライランは書き込み以外の
initの処理をすべて行うため、その終了コードは書き込み時の終了コードを予測します。既存の設定ファイルを書き込み時とまったく同じように、同じ理由で拒否するため、変更を確定する前にinitが成功するかどうかを確認するのに使えます。上書き書き込みで生成されるドキュメントを確認するには、--forceを併用します。--force --dry-runはマージ結果を報告し、それでも何も書き込みません。 - レポートされるコンテンツ内のポリシーは書き込み時に固定されるはずのポリシーであるため、公開されているトラストポリシーを取得するためにレジストリへの接続は引き続き行われます。ドライランは、書き込み時と同じく、そのレジストリ自身のオリジンに対して認証なしのリクエストを 1 回送信します。
--dry-runの下では、標準出力にはそのコンテンツのみが出力されるため、パース可能な状態が保たれます。コンテンツで表現できない唯一のものは「存在しないこと」です。レジストリがトラストポリシーを公開せず、ポリシーなしでシードされた場合、その旨を伝え、--identityまたは--keyでアイデンティティを固定するよう促す通知は標準エラーに出力されます。信頼済みアイデンティティを持たない設定ドキュメントは、固定されたポリシーがたまたま空だった場合も、ポリシーがまったく公開されていなかった場合も同じに見えるため、両方のストリームを読んでください。標準エラーを破棄するプログラムには、この点について何も伝わりません。レジストリがポリシーを公開している場合、または代わりに公式ハブの組み込みベースラインが固定された場合は、固定されたポリシーがレポートされるコンテンツ自体に含まれ、別途通知は出力されません。
シードされた設定は、所有して編集を続けるドキュメントであり、そのため書き込む代わりに返すことができます。一方、後述する有効な設定の固定は、設定が何に解決されたかの記録 (誰かが作成するコンテンツではなく、コンパイラが自身について保持する状態) を生成するため、常に書き込みを行い、--dry-run は提供しません。
config show — 現在適用されている設定を確認する
aggrega config show は、現在適用されている設定をレポートします。デフォルトの表示では、まず寄与した設定ファイルと環境オーバーライドのカスケードを優先度の低い順に示し、続いて有効なマージ済み設定 (グローバル設定、ワークスペースツリーのカスケード、および環境オーバーレイを 1 つの結果にまとめたもの) を出力します。この読み込みファイルのカスケードで、どのファイルと環境オーバーライドが現在の設定を形作ったかを確認できます。
2 つの絞り込み表示で出力を限定できます。
--globalまたは--workspaceは、単一レイヤーのファイルのバイト列をそのまま、コメントと書式を保持して出力します。そのレイヤーのファイルが存在しない場合は、失敗せずにその旨を表示します。この 2 つは同時に指定できません。--originは、有効な各設定に、その設定の由来となったレイヤー (コマンドラインフラグ、環境変数、設定ファイル、または組み込みのデフォルト) を優先度の高い順に注記します。フラグは入力したとおりに示されるため、今回の実行で--offlineによって決まった設定は、その由来として--offlineをレポートします。環境変数はenv:プレフィックスの後に名前が示され、設定ファイルは絶対パスで示されます。
--origin の下では、設定は、そのレイヤーがどのような値を書いているかにかかわらず、その設定を行う最も優先度の高いレイヤーに帰属します。そのため、default_registry: hub.aggrega.ai と書いたプロジェクトファイルは、組み込みのデフォルトが同じレジストリであってもその設定の由来として示され、グローバルファイルがすでに設定している値を再度記述したプロジェクトファイルは、グローバルファイルではなくそのプロジェクトファイルが示されます。どちらの場合も、そのファイルが値を保持しているファイルであり、デフォルトやその下のファイルが変わった日に、それを削除すると結果が変わるファイルだからです。どのレイヤーも設定していない設定は、組み込みのデフォルトをレポートします。
- 何をもって設定したとみなすか。 設定ファイルは、その設定のキーを含む場合に設定を行ったとみなされ、リスト設定の場合はリストの
_append対応キーを含む場合も該当します。環境変数は空でない値でエクスポートされている場合に、フラグは入力された場合にその設定を行ったとみなされます。--offline=falseは、--offlineと同様に確かにそのポスチャを設定します。 - パイプラインが所有する設定ファイルは、読み取りの対象となるキー、すなわちリストの追加と署名ポリシーについてのみ示されます。無視されて警告が出されるキーが、値の由来としてレポートされることはありません。
- リスト設定とマップ設定は全体として帰属します。帰属先は、それらを設定する最も優先度の高いレイヤーです。どのレイヤーがリストのどのエントリに寄与したかはレポートされません。
- 署名要件は唯一の例外です。 どのレイヤーもこれを有効にでき、どのレイヤーも無効にできないため、これを有効にした最初のレイヤーが示されます。
required: falseを書いたレイヤーは何も有効にしないため、どのレイヤーも有効にしていない場合、この設定は組み込みのデフォルトをレポートします。
config capture — ビルドに不可欠な設定を固定する
aggrega config capture は、有効なビルドに不可欠な設定をこのプロジェクトのワークスペース設定ファイルに書き込みます。これにより、ワークスペースはマシンのグローバル設定に依存せずに同一のビルドを行えます。レジストリのトラストポリシーのようなマシン全体のツール設定はキャプチャされません。これらはその性質上、グローバル設定に残ります。変更のない設定に対して再度実行すると、同じファイルがバイト単位で同一に書き直されます。
キャプチャされるサブセットは、プラグインソケットのアタッチメントの集合とカタログディレクトリです。
- デフォルトでは、キャプチャはレンダリング出力を決定するソケット、つまりプロバイダーのバインディングと transform ロールのガバナンスアタッチメントのみを固定します。バイト単位で同一のビルドのためにプロジェクトとともに持ち運ぶ必要があるのはそれらだけだからです。カタログディレクトリは常にキャプチャされます。
--all-pluginsは、キャプチャするソケットを広げ、verdict ロールのガバナンス、リンター、インポーターのソケットも含めます。これを指定しない場合、これら 3 つは環境ごとに自由に異なることができます。
キャプチャは常に書き込みを行い、代わりに内容を受け取る方法は提供しません。生成されるのは設定が何に解決されたかの記録であり、誰かが作成するドキュメントではないため、作成者がレビューして修正するものはありません。内容を報告すると、解決結果のスナップショットを編集するよう促すことになります。
キャプチャはワークスペース内にのみ書き込みます。ワークスペース内にないフォルダで、--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が指すディレクトリに実際に何が格納されるか、そしてそこにあってもどのロックファイルにも固定されていないエンティティがビルドで見つからない理由。