コンテンツにスキップ
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判定ロールのガバナンス、リンター、インポーターのゲートを含む、すべてのプラグインソケットを固定します。指定しない場合、capture はレンダリング結果を決定するソケット(プロバイダーのバインディングと変換ロールのガバナンスのアタッチメント)のみを固定します。

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 サブコマンドは、ビルドを制御する設定のシード、確認、固定を行います。どの設定をどのファイルに置くか、またレイヤーがどのように組み合わされるかについては、設定を参照してください。このページは、ほとんどのプロジェクトに必要な 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.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

1 行目は 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 が指すディレクトリに実際に何が格納されるか、そしてそこにあってもどのロックファイルにも固定されていないエンティティがビルドで見つからない理由。