콘텐츠로 이동
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-pluginsfalseverdict 역할의 거버넌스, 린터, 임포터 게이트를 포함한 모든 플러그인 소켓을 캡처합니다. 이 플래그가 없으면 capture는 렌더링 출력을 결정하는 소켓(provider 바인딩과 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쓰기를 제외한 모든 작업을 수행합니다. 초기화된 구성을 대상 파일 이름과 함께 내용으로 반환하며, 아무것도 생성하거나 수정하지 않습니다. 그 밖의 모든 동작은 쓰기와 동일하므로, 기존 config 파일은 쓰기가 거부하는 것과 똑같이 거부됩니다. 덮어쓰기 쓰기가 만들어 낼 병합 결과를 보려면 —force를 함께 전달합니다.
--forcefalse기존 config 파일을 덮어씁니다. 이 플래그가 없으면 대상 파일이 이미 존재할 때 init이 거부합니다.
--globalfalse모든 워크스페이스에서 공유되는 전역 config에 항목을 씁니다. 이것이 기본값입니다.
--registryhub.aggrega.ai신뢰 정책과 함께 초기화할 레지스트리 호스트입니다. 기본값은 공식 허브입니다.
--workspacefalse전역 config 대신 이 프로젝트의 워크스페이스 config에 항목을 씁니다.

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전역 config 파일 자체의 바이트를 주석과 서식을 유지한 채 그대로 출력합니다.
--originfalse각 유효한 설정에 그 설정이 온 계층(명령줄 플래그, 환경 변수, config 파일 또는 내장 기본값)을 주석으로 표시합니다.
--workspacefalse이 프로젝트의 워크스페이스 config 파일 자체의 바이트를 주석과 서식을 유지한 채 그대로 출력합니다.

동작

config 하위 명령은 빌드를 좌우하는 구성을 초기 생성하고, 검사하고, 고정합니다. 어떤 설정이 어느 파일에 속하는지와 계층이 어떻게 결합되는지는 구성을 참조하십시오. 이 문서는 대부분의 프로젝트에 필요한 두 파일부터 설명하고 나머지는 그 뒤에 다룹니다.

config init — 작동하는 구성 초기 생성

aggrega config init은 새 머신에서 레지스트리와 그 서명 신뢰 정책을 등록하여 구성을 초기 생성하므로, YAML을 직접 편집하지 않고도 서명된 아티팩트를 가져와 검증할 수 있습니다. 기본적으로 공식 허브(hub.aggrega.ai)를 서명 필수 및 공식 신뢰 ID와 함께 등록합니다. 레지스트리가 공시하는 신뢰 정책은 해당 레지스트리 자체 오리진에서 한 번 가져와 로컬에 고정됩니다(최초 사용 시 신뢰). 허브에 연결할 수 없거나, 아무것도 공시하지 않거나, 워크스페이스가 오프라인이면 내장된 공식 기준 정책이 대신 기록되므로 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, 파일이 있었고 --force로 init이 그 파일에 기록했으면 Using입니다. --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로 ID를 고정하라고 안내하는 알림은 표준 오류로 출력됩니다. 신뢰 ID가 없는 구성 문서는 고정된 정책이 우연히 비어 있었든 정책이 전혀 공시되지 않았든 똑같아 보이므로 두 스트림을 모두 읽으십시오. 표준 오류를 버리는 프로그램은 이에 대해 아무것도 알 수 없습니다. 레지스트리가 정책을 공시하거나 공식 허브의 내장 기준 정책이 대신 고정되면, 고정된 정책이 보고된 내용 자체에 포함되며 별도의 알림은 생성되지 않습니다.

초기 생성된 구성은 사용자가 소유하고 계속 편집하는 문서이므로 기록하는 대신 반환할 수 있습니다. 아래에서 설명하는 유효 구성 고정은 구성이 무엇으로 해석되었는지에 대한 기록, 즉 누군가 작성하는 내용이 아니라 컴파일러가 자신에 대해 유지하는 상태를 생성하므로 항상 기록하며 --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는 빌드에 중요한 유효 구성을 이 프로젝트의 워크스페이스 구성 파일에 기록하므로, 워크스페이스는 머신의 전역 구성에 의존하지 않고도 동일하게 빌드됩니다. 레지스트리의 신뢰 정책과 같은 머신 전체의 도구 설정은 캡처되지 않으며, 그 성격상 전역 구성에 남습니다. 변경되지 않은 구성에서 다시 실행하면 같은 파일을 바이트 단위까지 동일하게 다시 씁니다.

캡처되는 부분 집합은 플러그인 소켓 연결 집합과 카탈로그 디렉터리입니다.

  • 기본적으로 캡처는 렌더링 출력을 결정하는 소켓, 즉 provider 바인딩과 transform 역할의 거버넌스 연결만 고정합니다. 바이트 단위로 동일한 빌드를 위해 프로젝트와 함께 옮겨져야 하는 것은 이것들뿐이기 때문입니다. 카탈로그 디렉터리는 항상 캡처됩니다.
  • --all-plugins는 캡처되는 소켓을 넓혀 verdict 역할의 거버넌스, 린터, 임포터 소켓까지 포함합니다. 이 플래그가 없으면 이 세 가지는 환경에 따라 자유롭게 달라질 수 있습니다.

캡처는 항상 기록하며, 대신 내용을 돌려받는 방법은 제공하지 않습니다. 캡처가 만들어 내는 것은 구성이 무엇으로 해석되었는지에 대한 기록이지 누군가 작성하는 문서가 아니므로, 작성자가 검토하고 수정할 것이 없습니다. 이를 보고하면 해석 결과의 스냅숏을 편집하도록 유도하게 됩니다.

캡처는 워크스페이스 안에만 기록합니다. 워크스페이스 안에 있지 않은 폴더에서 --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가 가리키는 디렉터리에 실제로 무엇이 들어 있는지, 그리고 그곳에 있지만 어떤 lockfile도 고정하지 않은 엔터티를 빌드가 찾지 못하는 이유를 설명합니다.