aggrega config
Kiểm tra và quản lý cấu hình workspace
Cú pháp
aggrega configMô tả
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.Lệnh con
| Lệnh | Mô tả |
|---|---|
aggrega config capture | Cố định cấu hình hiệu lực quan trọng cho bản dựng vào workspace này |
aggrega config init | Khởi tạo một cấu hình hoạt động được với một registry và chính sách tin cậy của nó |
aggrega config show | Hiển thị cấu hình hiệu lực và nguồn gốc của từng thiết lập |
Mô tả 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.Các cờ của aggrega config capture
| Cờ | Mặc định | Mô tả |
|---|---|---|
--all-plugins | false | Ghi lại tất cả các socket plugin, bao gồm các cổng governance vai trò verdict, linter và importer. Nếu không có cờ này, capture chỉ cố định các socket quyết định đầu ra được render (các liên kết provider và các gắn kết governance vai trò transform). |
Mô tả 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.Các cờ của aggrega config init
| Cờ | Mặc định | Mô tả |
|---|---|---|
--dry-run | false | Làm mọi thứ trừ việc ghi: trả lại cấu hình được khởi tạo dưới dạng nội dung, nêu tên tệp mà nó dành cho, và không tạo hay sửa đổi gì. Mọi hành vi khác đều giống như khi ghi, nên một tệp cấu hình đã tồn tại bị từ chối đúng như khi ghi từ chối nó — hãy truyền thêm —force để xem kết quả hợp nhất mà một lần ghi đè sẽ tạo ra. |
--force | false | Ghi đè một tệp cấu hình đã tồn tại. Nếu không có cờ này, init từ chối khi tệp đích đã tồn tại. |
--global | false | Ghi mục vào cấu hình toàn cục được dùng chung cho mọi workspace. Đây là mặc định. |
--registry | hub.aggrega.ai | Máy chủ registry cần khởi tạo cùng chính sách tin cậy của nó. Mặc định là hub chính thức. |
--workspace | false | Ghi mục vào cấu hình workspace của dự án này thay vì cấu hình toàn cục. |
Mô tả 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.Các cờ của aggrega config show
| Cờ | Mặc định | Mô tả |
|---|---|---|
--global | false | In nguyên văn các byte của chính tệp cấu hình toàn cục, giữ nguyên chú thích và định dạng. |
--origin | false | Chú thích mỗi thiết lập hiệu lực bằng lớp mà nó đến từ (một cờ dòng lệnh, một biến môi trường, một tệp cấu hình, hoặc các giá trị mặc định tích hợp sẵn). |
--workspace | false | In nguyên văn các byte của chính tệp cấu hình workspace của dự án này, giữ nguyên chú thích và định dạng. |
Chức năng
Các lệnh con config khởi tạo, kiểm tra và đóng băng cấu hình chi phối một bản build. Để biết một thiết lập thuộc về tệp nào và các lớp kết hợp với nhau ra sao, xem Cấu hình — trang này bắt đầu với hai tệp mà hầu hết các dự án cần và để phần còn lại phía sau.
config init — khởi tạo một cấu hình hoạt động được
aggrega config init khởi tạo cấu hình trên một máy mới bằng cách đăng ký một registry và chính sách tin cậy chữ ký của nó, để các artifact đã ký được kéo về và xác minh mà không cần sửa YAML bằng tay. Theo mặc định, lệnh đăng ký hub chính thức (hub.aggrega.ai) với yêu cầu chữ ký và các danh tính tin cậy chính thức của nó. Chính sách tin cậy mà registry công bố được tải một lần từ chính nguồn gốc của nó và được ghim cục bộ (tin cậy ở lần dùng đầu tiên); khi không kết nối được tới hub, hub không công bố gì, hoặc workspace ở chế độ ngoại tuyến, đường cơ sở chính thức tích hợp sẵn của nó sẽ được ghi thay thế, nên init vẫn tạo ra một cấu hình dùng được khi ngoại tuyến.
Trước mọi việc khác, init cho biết mọi thứ nằm ở đâu. Khởi tạo trên một máy Linux mới sẽ mở đầu bằng:
Created the global configuration file at /home/you/.config/aggrega/config.yamlMachine-wide caches are kept in /home/you/.cache/aggregavà trên một máy Windows mới bằng:
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\cacheDòng đầu tiên nêu tên tệp cấu hình mà init đã ghi: Created khi tệp chưa tồn tại, và Using khi tệp đã có và --force cho phép init ghi vào đó; với --workspace, dòng này nêu tệp cấu hình workspace thay vì tệp toàn cục. Dòng thứ hai nêu thư mục chứa các bộ nhớ đệm dùng chung cho cả máy — các plugin đã biên dịch và mô tả của chúng — đây là nơi mỗi nền tảng lưu bộ nhớ đệm của người dùng; Bộ nhớ đệm nào thuộc về dự án này, và bộ nhớ đệm nào thuộc về máy đưa ra quy tắc cho từng nền tảng. Mỗi dòng kết thúc bằng đường dẫn của nó và không có gì phía sau, nên có thể sao chép đường dẫn nguyên trạng. Các dòng tiếp theo thuộc về chính việc đăng ký: việc tải chính sách tin cậy tìm thấy gì, và registry được đăng ký trong tệp nào. Một lần khởi tạo bị từ chối không in dòng nào trong hai dòng này, vì nó không tạo ra gì, và --dry-run cũng vậy, vì đầu ra chuẩn của nó chỉ chứa nội dung được trả về.
--registry <host>khởi tạo một registry khác — một hub cách ly mạng hoặc riêng tư — thay cho registry chính thức. Registry như vậy không có đường cơ sở tích hợp sẵn, nên khi nó không công bố gì, mục sẽ được ghi mà không có chính sách, và trong một workspace ngoại tuyến, việc khởi tạo nó bị từ chối (mã ngắnE0310): chính sách không thể tải về, vàinitkhông nhận--identityhay--keyđể ghim chính sách bằng tay. Hãy khởi tạo nó một lần khi trực tuyến, hoặc thêm nó bằngaggrega registry addcùng một chính sách do bạn cung cấp.- Nếu tệp đích đã tồn tại,
inittừ chối thay vì ghi đè;--forcevẫn ghi, hợp nhất mục registry vào tệp hiện có và giữ nguyên các thiết lập khác. --dry-runlàm mọi việcinitlàm ngoại trừ ghi. Nó trả cấu hình đã khởi tạo về dưới dạng nội dung, không tạo hay sửa đổi gì, và câu trả lời nêu tên tệp mà nội dung dành cho — điều này quan trọng ở đây, vì đích là cấu hình toàn cục trừ khi--workspacechọn cấu hình riêng của dự án này. Một bên gọi có mô hình tài liệu riêng, chẳng hạn một trình soạn thảo, đặt nội dung vào đó, nơi nó hiển thị trước khi được lưu và có thể được chỉnh sửa hoặc hoàn tác.- Vì một lần chạy thử làm mọi việc khác mà
initlàm, mã thoát của nó dự báo mã thoát của lần ghi. Nó từ chối một tệp cấu hình hiện có đúng như một lần ghi từ chối, và vì cùng lý do, nên bạn có thể dùng nó để hỏi xeminitcó thành công hay không trước khi cam kết thay đổi. Để xem tài liệu mà một lần ghi đè sẽ tạo ra, hãy truyền--forcecùng với nó:--force --dry-runbáo cáo kết quả hợp nhất và vẫn không ghi gì. - Registry vẫn được liên hệ để lấy chính sách tin cậy nó công bố, vì chính sách trong nội dung được báo cáo là chính sách mà một lần ghi sẽ ghim. Một lần chạy thử thực hiện cùng một yêu cầu không xác thực duy nhất tới nguồn gốc của chính registry đó như một lần ghi.
- Với
--dry-run, đầu ra chuẩn chỉ chứa nội dung đó và không gì khác, nên vẫn phân tích được. Điều duy nhất nội dung không thể biểu đạt là sự vắng mặt: khi một registry không công bố chính sách tin cậy nào và được khởi tạo không có chính sách, thông báo nói điều đó — và bảo bạn ghim danh tính bằng--identityhoặc--key— được gửi tới đầu ra lỗi chuẩn. Một tài liệu cấu hình không có danh tính tin cậy nào trông giống nhau dù một chính sách đã được ghim và tình cờ rỗng hay hoàn toàn không có chính sách nào được công bố, vì vậy hãy đọc cả hai luồng; một chương trình bỏ qua đầu ra lỗi chuẩn sẽ không được biết gì về điều này. Khi registry có công bố chính sách, hoặc đường cơ sở tích hợp sẵn của hub chính thức được ghim thay thế, chính sách đã ghim nằm ngay trong nội dung được báo cáo và không có thông báo riêng nào được tạo ra.
Một cấu hình đã khởi tạo là tài liệu bạn sở hữu và tiếp tục chỉnh sửa, đó là lý do nó có thể được trả về thay vì được ghi. Việc đóng băng cấu hình hiệu lực, ở phần dưới, tạo ra một bản ghi về kết quả phân giải của cấu hình — trạng thái mà trình biên dịch lưu về chính nó chứ không phải nội dung do ai đó soạn — nên nó luôn ghi và không cung cấp --dry-run.
config show — kiểm tra những gì đang áp dụng
aggrega config show báo cáo cấu hình đang áp dụng ngay lúc này. Trong chế độ xem mặc định, lệnh mở đầu bằng chuỗi các tệp cấu hình và các ghi đè từ biến môi trường đã đóng góp, theo thứ tự ưu tiên thấp nhất trước, rồi in cấu hình hợp nhất hiệu lực — cấu hình toàn cục, chuỗi theo cây workspace và mọi lớp phủ môi trường được kết hợp thành một kết quả duy nhất. Chuỗi tệp đã nạp này là nơi bạn xác nhận những tệp và ghi đè môi trường nào đã định hình cấu hình hiện tại.
Hai chế độ xem tập trung thu hẹp đầu ra:
--globalhoặc--workspacein nguyên văn các byte của tệp thuộc một lớp duy nhất, giữ nguyên chú thích và định dạng; khi tệp của lớp đó không tồn tại, lệnh nói như vậy thay vì thất bại. Hai cờ này loại trừ lẫn nhau.--originchú thích mỗi thiết lập hiệu lực với lớp mà nó đến từ — một cờ dòng lệnh, một biến môi trường, một tệp cấu hình, hoặc các giá trị mặc định tích hợp sẵn, theo thứ tự ưu tiên cao nhất trước. Một cờ được nêu tên đúng như bạn đã gõ, nên một thiết lập do--offlinequyết định trong lần chạy này báo cáo--offlinelà nguồn của nó; một biến môi trường được nêu tên sau tiền tốenv:và một tệp cấu hình theo đường dẫn tuyệt đối của nó.
Với --origin, một thiết lập được quy cho lớp có độ ưu tiên cao nhất đặt nó, bất kể lớp đó ghi giá trị gì. Vì vậy một tệp dự án ghi default_registry: hub.aggrega.ai được nêu tên cho thiết lập đó dù giá trị mặc định tích hợp sẵn là cùng registry đó, và một tệp dự án nhắc lại giá trị mà tệp toàn cục đã đặt được nêu tên thay vì tệp toàn cục: trong cả hai trường hợp, đó là tệp đang giữ giá trị tại chỗ, và là tệp mà việc xóa nó sẽ thay đổi câu trả lời vào ngày giá trị mặc định hoặc tệp bên dưới thay đổi. Một thiết lập không được lớp nào đặt sẽ báo cáo các giá trị mặc định tích hợp sẵn.
- Thế nào được tính là đặt thiết lập. Một tệp cấu hình đặt một thiết lập khi nó chứa khóa của thiết lập đó, và với thiết lập dạng danh sách thì cả khi nó chứa khóa đi kèm
_appendcủa danh sách. Một biến môi trường đặt thiết lập của nó khi được export với giá trị không rỗng, và một cờ khi bạn gõ nó —--offline=falseđặt trạng thái chắc chắn như--offline. - Một tệp cấu hình do pipeline của bạn sở hữu chỉ được nêu tên cho các khóa mà nó được đọc, tức là các phần bổ sung danh sách và chính sách ký. Một khóa mà nó bỏ qua, và cảnh báo về, không bao giờ được báo cáo là nguồn của một giá trị.
- Các thiết lập dạng danh sách và map được quy trọn vẹn, cho lớp có độ ưu tiên cao nhất đặt chúng; lớp nào đóng góp mục nào của danh sách thì không được báo cáo.
- Yêu cầu ký là ngoại lệ duy nhất. Bất kỳ lớp nào cũng có thể bật nó và không lớp nào có thể tắt nó, nên nó nêu tên lớp đầu tiên bật nó. Một lớp ghi
required: falsekhông bật gì cả, nên khi không lớp nào bật nó, thiết lập báo cáo các giá trị mặc định tích hợp sẵn.
config capture — cố định các thiết lập quan trọng cho bản dựng
aggrega config capture ghi cấu hình hiệu lực quan trọng cho bản dựng vào tệp cấu hình workspace của dự án này, để workspace dựng ra kết quả giống hệt nhau mà không phụ thuộc vào cấu hình toàn cục của máy. Các thiết lập công cụ áp dụng cho toàn máy, chẳng hạn chính sách tin cậy của một registry, không được ghi lại; về bản chất, chúng nằm trong cấu hình toàn cục. Chạy lại lệnh trên một cấu hình không đổi sẽ ghi lại đúng tệp đó, giống hệt từng byte.
Tập con được ghi lại gồm một tập các liên kết socket của plugin và các thư mục catalog:
- Theo mặc định, capture chỉ cố định các socket quyết định đầu ra được kết xuất — các liên kết provider và các liên kết governance vai trò transform — vì chỉ những socket đó cần đi cùng dự án để có các bản dựng giống hệt từng byte. Các thư mục catalog luôn được ghi lại.
--all-pluginsmở rộng các socket được ghi lại để bao gồm cả các socket governance vai trò verdict, linter và importer. Nếu không có cờ này, ba loại socket đó vẫn được tự do thay đổi theo môi trường.
Capture luôn ghi, và không có cách nào để nhận lại nội dung thay vì ghi. Thứ nó tạo ra là bản ghi về kết quả phân giải của cấu hình, không phải một tài liệu do ai đó soạn, nên không có gì để tác giả xem xét và sửa đổi — việc trả về nội dung sẽ khuyến khích chỉnh sửa một ảnh chụp của một kết quả phân giải.
Lệnh capture chỉ ghi vào bên trong một workspace. Khi chạy trong một thư mục không nằm trong workspace nào, mà không có --workspace-root hay AGGREGA_WORKSPACE_ROOT chỉ định một workspace, nó không ghi gì cả — một tệp cấu hình được ghi ở đó sẽ biến thư mục thành một workspace — và thoát với một lỗi cho biết điều đó. aggrega config init --workspace biến thư mục thành một workspace trước.
Xem thêm
- configuration.md — một thiết lập thuộc về tệp nào, thang thứ tự ưu tiên, và các cơ chế mà một dự án lớn hơn sử dụng.
- global-flags.md — các cờ
--configvà--workspace-root. - environment-variables.md — các biến
AGGREGA_*ghi đè cấu hình khi chạy. - aggrega-registry.md — quản lý trực tiếp các registry và chính sách tin cậy của chúng.
- aggrega-cache.md — thư mục mà
artifact_cache_dirchỉ định thực sự chứa gì, và vì sao một thực thể nằm ở đó mà không lockfile nào ghim lại không được bản build tìm thấy.