Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

aggrega config

Memeriksa dan mengelola konfigurasi workspace

Sinopsis

aggrega config

Deskripsi

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.

Subperintah

PerintahDeskripsi
aggrega config captureMembekukan konfigurasi efektif yang penting bagi build ke dalam workspace ini
aggrega config initMenyiapkan konfigurasi yang berfungsi dengan registry dan kebijakan kepercayaannya
aggrega config showMenampilkan konfigurasi efektif dan asal setiap pengaturan

Deskripsi 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.

Flag aggrega config capture

FlagDefaultDeskripsi
--all-pluginsfalseMenangkap semua socket plugin, termasuk gerbang tata kelola berperan verdict, linter, dan importer. Tanpa opsi ini, capture hanya membekukan socket yang menentukan output yang dirender (binding provider dan lampiran tata kelola berperan transform).

Deskripsi 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.

Flag aggrega config init

FlagDefaultDeskripsi
--dry-runfalseMelakukan segalanya kecuali menulis: mengembalikan konfigurasi yang disiapkan sebagai konten, dengan menyebut file tujuannya, dan tidak membuat atau mengubah apa pun. Semua perilaku lainnya adalah perilaku penulisan, sehingga file konfigurasi yang sudah ada ditolak persis seperti penulisan menolaknya — berikan —force bersamanya untuk penggabungan yang akan dihasilkan penulisan yang menimpa.
--forcefalseMenimpa file konfigurasi yang sudah ada. Tanpa opsi ini, init menolak ketika file target sudah ada.
--globalfalseMenulis entri ke konfigurasi global yang dipakai bersama oleh semua workspace. Ini adalah default-nya.
--registryhub.aggrega.aiHost registry yang akan disiapkan dengan kebijakan kepercayaannya. Default-nya adalah hub resmi.
--workspacefalseMenulis entri ke konfigurasi workspace proyek ini alih-alih konfigurasi global.

Deskripsi 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.

Flag aggrega config show

FlagDefaultDeskripsi
--globalfalseMencetak byte file konfigurasi global apa adanya, dengan mempertahankan komentar dan pemformatannya.
--originfalseMemberi anotasi pada setiap pengaturan efektif dengan lapisan asalnya (flag baris perintah, variabel lingkungan, file konfigurasi, atau default bawaan).
--workspacefalseMencetak byte file konfigurasi workspace proyek ini apa adanya, dengan mempertahankan komentar dan pemformatannya.

Apa yang dilakukannya

Subperintah config menyiapkan, memeriksa, dan membekukan konfigurasi yang mengatur build. Untuk mengetahui file mana yang menjadi tempat sebuah pengaturan dan bagaimana lapisan-lapisan digabungkan, lihat Konfigurasi — halaman itu dimulai dengan dua file yang dibutuhkan sebagian besar proyek dan menempatkan sisanya di belakang.

config init — menyiapkan konfigurasi yang berfungsi

aggrega config init menyiapkan konfigurasi di mesin baru dengan mendaftarkan registry dan kebijakan kepercayaan tanda tangannya, sehingga artefak bertanda tangan dapat di-pull dan diverifikasi tanpa mengedit YAML secara manual. Secara default, perintah ini mendaftarkan hub resmi (hub.aggrega.ai) dengan tanda tangan wajib dan identitas tepercaya resminya. Kebijakan kepercayaan yang diumumkan registry diambil sekali dari origin-nya sendiri dan di-pin secara lokal (trust-on-first-use); ketika hub tidak dapat dijangkau, tidak mengumumkan apa pun, atau workspace sedang offline, baseline resmi bawaannya ditulis sebagai gantinya, sehingga init tetap menghasilkan konfigurasi yang dapat digunakan secara offline.

Sebelum hal lain, init menyatakan di mana segala sesuatu berada. Penyiapan mesin Linux baru dibuka dengan:

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

dan mesin Windows baru dengan:

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

Baris pertama menyebut file konfigurasi yang ditulis init: Created ketika file belum ada, dan Using ketika file sudah ada dan --force mengizinkan init menulis ke dalamnya; dengan --workspace, baris ini menyebut file konfigurasi workspace alih-alih yang global. Baris kedua menyebut direktori tempat cache tingkat mesin — plugin terkompilasi dan deskripsinya — disimpan, yaitu tempat setiap platform menyimpan cache pengguna; Cache mana yang milik proyek ini, dan mana yang milik mesin memberikan aturannya per platform. Setiap baris diakhiri dengan path-nya dan tidak ada apa pun sesudahnya, sehingga path dapat disalin apa adanya. Baris-baris berikutnya adalah milik pendaftaran itu sendiri: apa yang ditemukan pengambilan kebijakan kepercayaan, dan di file mana registry didaftarkan. Penyiapan yang ditolak tidak mencetak kedua baris tersebut, karena tidak membuat apa pun, begitu pula --dry-run, yang output standarnya hanya memuat konten yang dikembalikannya.

  • --registry <host> menyiapkan registry lain — hub air-gapped atau privat — alih-alih yang resmi. Registry seperti itu tidak memiliki baseline bawaan, sehingga jika registry tersebut tidak mengumumkan apa pun, entri ditulis tanpa kebijakan, dan di workspace offline penyiapannya ditolak (kode singkat E0310): kebijakan tidak dapat diambil, dan init tidak menerima --identity atau --key untuk mem-pin kebijakan secara manual. Siapkan registry tersebut sekali saat online, atau tambahkan dengan aggrega registry add dan kebijakan yang Anda berikan.
  • Jika file target sudah ada, init menolak alih-alih menimpanya; --force tetap menulis, dengan menggabungkan entri registry ke dalam file yang ada dan mempertahankan pengaturan lainnya.
  • --dry-run melakukan semua yang dilakukan init kecuali menulis. Opsi ini mengembalikan konfigurasi yang disiapkan sebagai konten, tanpa membuat atau mengubah apa pun, dan jawabannya menyebut file tujuan konten tersebut — yang penting di sini, karena targetnya adalah konfigurasi global kecuali --workspace memilih konfigurasi milik proyek ini. Pemanggil yang mengelola model dokumennya sendiri, seperti editor, menaruh konten tersebut di sana, tempat konten itu terlihat sebelum disimpan dan dapat diubah atau dibatalkan.
  • Karena dry run melakukan semua hal lain yang dilakukan init, kode keluarnya memprediksi kode keluar penulisan. Dry run menolak file konfigurasi yang sudah ada persis seperti penulisan menolaknya, dan dengan alasan yang sama, sehingga Anda dapat menggunakannya untuk menanyakan apakah init akan berhasil sebelum berkomitmen pada perubahan. Untuk melihat dokumen yang akan dihasilkan penulisan yang menimpa, berikan --force bersamanya: --force --dry-run melaporkan penggabungan dan tetap tidak menulis apa pun.
  • Registry tetap dihubungi untuk kebijakan kepercayaan yang diumumkannya, karena kebijakan dalam konten yang dilaporkan adalah kebijakan yang akan di-pin oleh penulisan. Dry run membuat satu permintaan tanpa autentikasi yang sama ke origin registry tersebut seperti yang dibuat penulisan.
  • Dengan --dry-run, output standar memuat konten tersebut dan tidak ada yang lain, sehingga tetap dapat di-parse. Satu-satunya hal yang tidak dapat diekspresikan konten adalah ketiadaan: ketika registry tidak mengumumkan kebijakan kepercayaan dan disiapkan tanpa kebijakan, pemberitahuan tentang hal itu — yang meminta Anda mem-pin identitas dengan --identity atau --key — dikirim ke standard error. Dokumen konfigurasi tanpa identitas tepercaya terlihat sama, baik ketika sebuah kebijakan di-pin dan kebetulan kosong maupun ketika tidak ada kebijakan yang diumumkan sama sekali, jadi bacalah kedua stream; program yang membuang standard error tidak diberi tahu apa pun tentangnya. Ketika registry memang mengumumkan kebijakan, atau baseline bawaan hub resmi di-pin sebagai gantinya, kebijakan yang di-pin ada di dalam konten yang dilaporkan itu sendiri dan tidak ada pemberitahuan terpisah yang dihasilkan.

Konfigurasi yang disiapkan adalah dokumen milik Anda yang terus Anda edit, itulah sebabnya konfigurasi tersebut dapat dikembalikan alih-alih ditulis. Membekukan konfigurasi efektif, di bawah, menghasilkan catatan tentang hasil resolusi konfigurasi — status yang disimpan compiler tentang dirinya sendiri, bukan konten yang disusun seseorang — sehingga operasi itu selalu menulis dan tidak menawarkan --dry-run.

config show — memeriksa apa yang berlaku saat ini

aggrega config show melaporkan konfigurasi yang berlaku saat ini. Dalam tampilan default-nya, perintah ini diawali dengan kaskade file konfigurasi dan penimpaan lingkungan yang berkontribusi, mulai dari prioritas terendah, lalu mencetak konfigurasi gabungan yang efektif — konfigurasi global, kaskade pohon workspace, dan lapisan lingkungan apa pun yang digabungkan menjadi satu hasil. Kaskade file yang dimuat ini adalah tempat Anda memastikan file dan penimpaan lingkungan mana yang membentuk konfigurasi saat ini.

Dua tampilan terfokus mempersempit output:

  • --global atau --workspace mencetak byte file milik satu lapisan apa adanya, dengan komentar dan pemformatan dipertahankan; ketika file lapisan itu tidak ada, perintah ini menyatakannya alih-alih gagal. Keduanya saling eksklusif.
  • --origin memberi anotasi pada setiap pengaturan efektif dengan lapisan asalnya — flag baris perintah, variabel lingkungan, file konfigurasi, atau default bawaan, mulai dari prioritas tertinggi. Flag disebut sebagaimana Anda mengetiknya, sehingga pengaturan yang ditentukan --offline pada proses ini melaporkan --offline sebagai sumbernya; variabel lingkungan disebut di belakang awalan env: dan file konfigurasi dengan path absolutnya.

Dengan --origin, pengaturan diatribusikan ke lapisan berprioritas tertinggi yang mengaturnya, apa pun nilai yang ditulis lapisan itu. Jadi, file proyek yang menulis default_registry: hub.aggrega.ai disebut untuk pengaturan tersebut meskipun default bawaannya adalah registry yang sama, dan file proyek yang menyatakan ulang nilai yang sudah diatur file global disebut alih-alih file global: dalam kedua kasus, itulah file yang menahan nilai di tempatnya, dan file yang penghapusannya mengubah jawabannya pada hari default atau file di bawahnya berubah. Pengaturan yang tidak diatur oleh lapisan mana pun melaporkan default bawaan.

  • Apa yang dihitung sebagai mengaturnya. File konfigurasi mengatur sebuah pengaturan ketika memuat kunci pengaturan itu, dan pengaturan daftar juga ketika memuat pendamping _append dari daftar tersebut. Variabel lingkungan mengatur pengaturannya ketika diekspor dengan nilai yang tidak kosong, dan flag ketika Anda mengetiknya — --offline=false mengatur mode sama pastinya dengan --offline.
  • File konfigurasi yang dimiliki pipeline Anda hanya disebut untuk kunci yang dibaca darinya, yaitu tambahan daftarnya dan kebijakan penandatanganan. Kunci yang diabaikannya, dan yang diperingatkannya, tidak pernah dilaporkan sebagai asal suatu nilai.
  • Pengaturan daftar dan map diatribusikan secara keseluruhan, ke lapisan berprioritas tertinggi yang mengaturnya; lapisan mana yang menyumbang entri mana dari sebuah daftar tidak dilaporkan.
  • Persyaratan penandatanganan adalah satu-satunya pengecualian. Lapisan mana pun dapat mengaktifkannya dan tidak ada yang dapat menonaktifkannya, sehingga yang disebut adalah lapisan pertama yang mengaktifkannya. Lapisan yang menulis required: false tidak mengaktifkan apa pun, sehingga jika tidak ada lapisan yang mengaktifkannya, pengaturan tersebut melaporkan default bawaan.

config capture — membekukan pengaturan yang penting bagi build

aggrega config capture menulis konfigurasi efektif yang penting bagi build ke dalam file konfigurasi workspace proyek ini, sehingga workspace mem-build secara identik tanpa bergantung pada konfigurasi global mesin. Pengaturan perkakas tingkat mesin seperti kebijakan kepercayaan registry tidak ditangkap; pengaturan tersebut pada dasarnya tetap berada di konfigurasi global. Menjalankannya lagi pada konfigurasi yang tidak berubah menulis ulang file yang sama byte demi byte.

Subset yang ditangkap adalah sekumpulan lampiran socket plugin dan direktori katalog:

  • Secara default, capture hanya membekukan socket yang menentukan output yang dirender — binding provider dan lampiran tata kelola berperan transform — karena hanya socket tersebut yang harus ikut bersama proyek untuk build yang identik byte demi byte. Direktori katalog selalu ditangkap.
  • --all-plugins memperluas socket yang ditangkap agar juga mencakup socket tata kelola berperan verdict, linter, dan importer. Tanpa opsi ini, ketiganya bebas bervariasi menurut lingkungan.

Capture selalu menulis, dan tidak menawarkan cara untuk menerima kontennya sebagai gantinya. Yang dihasilkannya adalah catatan tentang hasil resolusi konfigurasi, bukan dokumen yang disusun seseorang, sehingga tidak ada yang perlu ditinjau dan diubah oleh penulis — melaporkannya akan mengundang pengeditan snapshot dari sebuah resolusi.

Penangkapan hanya menulis ke dalam workspace. Jika dijalankan di folder yang tidak berada di dalam workspace, tanpa --workspace-root atau AGGREGA_WORKSPACE_ROOT yang menyebut workspace, perintah ini tidak menulis apa pun — file konfigurasi yang ditulis di sana akan mengubah folder itu menjadi workspace — dan keluar dengan galat yang menyatakan hal itu. aggrega config init --workspace menjadikan folder tersebut workspace terlebih dahulu.

Lihat juga

  • configuration.md — file mana yang menjadi tempat sebuah pengaturan, tangga prioritas, dan mekanisme yang digunakan proyek yang lebih besar.
  • global-flags.md — flag --config dan --workspace-root.
  • environment-variables.md — variabel AGGREGA_* yang menimpa konfigurasi saat runtime.
  • aggrega-registry.md — mengelola registry dan kebijakan kepercayaannya secara langsung.
  • aggrega-cache.md — apa yang sebenarnya disimpan direktori yang disebut artifact_cache_dir, dan mengapa entitas yang berada di sana tetapi tidak di-pin lockfile mana pun tidak ditemukan oleh build.