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

Variabel lingkungan

CLI aggrega membaca sekumpulan tetap variabel lingkungan berawalan AGGREGA_. Masing-masing menimpa pengaturan .aggrega-config.yaml yang bersesuaian saat runtime — lapisan yang dikendalikan oleh job CI atau orkestrator penyuntik rahasia tanpa mengedit file yang terlacak — sementara flag baris perintah tetap mengungguli semuanya.

Prioritas

Variabel lingkungan berada di atas file konfigurasi yang di-commit — sebuah penimpaan saat runtime yang diterapkan oleh pipeline atau orkestrator penyuntik rahasia tanpa mengedit file yang dilacak — dan di bawah flag baris perintah, sehingga nilai eksplisit yang diketik di baris perintah tidak pernah ditimpa secara diam-diam oleh lingkungan sekitar. Konfigurasi memuat urutan lengkapnya beserta pelapisan file di bawahnya.

Variabel yang tidak diatur (atau kosong) diteruskan ke lapisan di bawahnya — variabel tersebut tidak pernah menimpa nilai yang telah dikonfigurasi dengan nilai kosong. Untuk melihat konfigurasi yang berlaku saat ini, beserta lapisan yang menentukan setiap pengaturan, jalankan aggrega config show --origin.

Penamaan

Nama variabel adalah AGGREGA_ diikuti jalur konfigurasinya dalam format huruf besar dengan garis bawah (titik menjadi garis bawah): signing.fulcio_url menjadi AGGREGA_SIGNING_FULCIO_URL. Satu nama dipersingkat demi kemudahan penggunaan — workspace.catalog_dirs terikat ke AGGREGA_CATALOG_DIRS, sejajar dengan PATH.

Pengaturan per registri (registries[].*) tidak memiliki variabel lingkungan: daftar blok kebijakan per host tidak dapat dinyatakan sebagai satu variabel, dan kebijakan kepercayaan serta penandatanganan sebuah registri adalah konfigurasi yang di-commit, bukan penimpaan dari lingkungan. Flag situasional, sekali pakai, dan posisional (--dry-run, --trace, --detail, --output, --skip-verify, --release, --entity, dan keluarga lint --allow-*/--no-allow-*) juga tidak memiliki variabel lingkungan — flag tersebut merupakan keputusan per eksekusi.

Pengaturan yang didukung konfigurasi

VariabelJalur konfigurasiCatatan
AGGREGA_DEFAULT_REGISTRYdefault_registryHost tujuan/registry (hub.aggrega.ai secara default). Ditulis dengan cara yang sama seperti default_registry ditulis dalam file — lihat cara menulis host registry — dan nilai yang tidak ditulis demikian ditolak saat konfigurasi di-resolve, dengan menyebut variabel ini.
AGGREGA_OFFLINEofflineBoolean. Melarang semua lalu lintas jaringan keluar: setiap perintah yang akan mengambil, menarik, memperoleh, mendorong, menandatangani, atau menghubungi registry menolak secara terang-terangan alih-alih membuka koneksi, dan build hanya memakai apa yang sudah dimiliki mesin — lockfile-nya, cache-nya, dan direktori katalog lokalnya, tempat --auto-pull mengisi entitas katalog lockfile tanpa menjangkau registry (Recipe yang chart-nya diambil dari sumber jarak jauh tetap berhenti saat offline). Penemuan kemudian membaca indeks lokal — pemberitahuan deprecation disajikan dari indeks yang sudah dibangun alih-alih diperiksa secara langsung, dan tingkat resolusi katalog registry jarak jauh dilewati; petunjuk plugin yang dicetak oleh perintah yang tidak dikenali hanya membaca indeks lokal, apa pun nilai pengaturan ini. Verifikasi material yang sudah di-cache atau di-pin tetap berjalan — offline melarang pengambilan, bukan pemeriksaan lokal. --offline adalah flag di atasnya, ke dua arah: flag ini menetapkan sikap untuk satu kali eksekusi, dan --offline=false mengizinkan jaringan untuk satu kali eksekusi ketika variabel ini atau file konfigurasi telah menetapkannya.
AGGREGA_AUTO_PULLauto_pullBoolean. Mengambil dependensi yang hilang secara otomatis saat build.
AGGREGA_ARTIFACT_CACHE_DIRartifact_cache_dirDirektori cache konten di disk, ditulis relatif terhadap root workspace sehingga menunjuk direktori yang sama di mana pun perintah dijalankan. Nilai absolut ditolak, begitu pula nilai yang menunjuk root workspace itu sendiri — berikan cache subdirektorinya sendiri.
AGGREGA_CATALOG_DIRSworkspace.catalog_dirsDipisahkan dengan pemisah daftar jalur OS (: di Unix). Berikan jalur absolut. Menggantikan daftar yang dikonfigurasi; Release yang diberi daftarnya sendiri di bawah workspace.releases mempertahankan daftar tersebut.
AGGREGA_SIGNING_FULCIO_URLsigning.fulcio_urlURL CA Fulcio untuk penandatanganan tanpa kunci.
AGGREGA_SIGNING_REKOR_URLsigning.rekor_urlURL log transparansi Rekor untuk penandatanganan tanpa kunci.
AGGREGA_SIGNING_TIMESTAMP_URLsigning.timestamp_urlURL otoritas stempel waktu RFC3161 untuk penandatanganan tanpa kunci.
AGGREGA_SIGNING_KEY_PATHsigning.key_pathJalur ke PEM kunci ECDSA P-256 yang dimiliki untuk penandatanganan berkunci. Hanya penunjuk jalur — tidak pernah material kunci.
AGGREGA_SIGNING_REQUIREDsigning.requiredBoolean. Mewajibkan tanda tangan untuk menerbitkan dan mengonsumsi jenis-jenis yang dicakup signing.kinds. Variabel ini hanya menyalakan kewajiban tersebut dan tidak pernah mematikannya: file konfigurasi yang menyetelnya tetap membuatnya menyala.
AGGREGA_SIGNING_KINDSsigning.kindsDipisahkan dengan pemisah daftar path OS (: di Unix), setiap entri adalah sebuah jenis sebagaimana kind:-nya ditulis, atau all. Variabel ini memperluas jenis yang dicakup kewajiban dan tidak pernah mempersempitnya; nilai yang bukan jenis yang dapat ditandatangani ditolak, dengan menyebut variabel ini.
AGGREGA_SKIP_SIGNATURE_VERIFICATIONskip_signature_verificationBoolean. Menonaktifkan verifikasi tanda tangan secara global — secara terang-terangan: setiap pull mencatat peringatan.
AGGREGA_WORKSPACE_ROOT(berpasangan dengan --workspace-root)Root workspace absolut, melewati penemuan — pada setiap perintah, dan untuk setiap permintaan ke aggrega mcp yang tidak menyebut workspace-nya sendiri. Bukan field konfigurasi; flag menang jika ditetapkan. Jika diisi kosong, dibaca sebagai tidak ditetapkan — kecuali oleh aggrega mcp melalui input dan output standar yang membawa AGGREGA_BUNDLE_VERSION dan tidak diberi --workspace-root, yaitu peluncuran oleh bundle desktop dengan pengaturan Workspace folder kosong, yang menjawab setiap panggilan yang tidak menyebut workspace-nya sendiri dengan penolakan yang menyebut pengaturan tersebut. Jika nilainya tidak menunjuk folder yang ada, setiap perintah yang membaca workspace-nya menolak sebelum melakukan apa pun, aggrega serve dan listener aggrega mcp menolak untuk dimulai, dan aggrega mcp melalui input dan output standar tetap dimulai dan menjawab setiap panggilan yang bertindak di workspace tersebut dengan penolakan — masing-masing menyebut variabel ini beserta pengaturan Workspace folder aplikasi desktop yang menetapkannya, dan mengutip nilainya sebagaimana diberikan.
AGGREGA_BUNDLE_VERSION(ditetapkan oleh bundle desktop)Versi bundle desktop yang meluncurkan aggrega mcp, yang ditetapkan bundle pada environment server. Bukan field konfigurasi. Server membacanya sekali saat dimulai dan melaporkannya di samping versinya sendiri pada describe-capabilities yang dipanggil tanpa argumen, dengan menyebutkan bila keduanya berasal dari rilis yang berbeda; tidak ada yang menolak karena perbedaan tersebut. Keberadaannya juga menandai peluncuran oleh bundle, sehingga AGGREGA_WORKSPACE_ROOT kosong di sampingnya ditolak alih-alih dibaca sebagai tidak ditetapkan, sebagaimana dijelaskan pada baris di atas. Jika diisi kosong, dibaca sebagai tidak ditetapkan.

AGGREGA_CONFIG menunjuk ke file konfigurasi global eksplisit yang dimuat di bawah file milik proyek; variabel ini memilih file mana yang berlaku alih-alih menimpa satu pengaturan. Jika tidak ditetapkan, lapisan itu dimuat otomatis dari lokasi default platform — di Windows aggrega\config.yaml di dalam direktori yang ditunjuk variabel environment APPDATA, dan di tempat lain aggrega/config.yaml di dalam direktori yang ditunjuk XDG_CONFIG_HOME, dengan fallback ke ~/.config/aggrega/config.yaml. Lihat Konfigurasi.

Lokasi file milik mesin

File konfigurasi global dan cache tingkat mesin berada di tempat setiap platform menyimpan file milik pengguna, sehingga aggrega juga membaca variabel yang menunjuk tempat-tempat tersebut. Tidak satu pun merupakan variabel AGGREGA_ dan tidak satu pun menimpa pengaturan: masing-masing menyatakan di mana sebuah file dicari bila tidak ada yang menunjuknya.

VariabelDibaca diYang ditempatkannya
APPDATAWindowsFile konfigurasi global, di aggrega\config.yaml di dalam direktori yang ditunjuk APPDATA.
LOCALAPPDATAWindowsCache tingkat mesin, di bawah aggrega\cache di dalam direktori yang ditunjuk LOCALAPPDATA.
XDG_CONFIG_HOME, lalu HOMELinux, macOS, dan sistem Unix lainnyaFile konfigurasi global, di aggrega/config.yaml di dalam direktori yang ditunjuk XDG_CONFIG_HOME, atau di ~/.config/aggrega/config.yaml bila XDG_CONFIG_HOME tidak ditetapkan.
XDG_CACHE_HOME, lalu HOMELinux dan sistem Unix lainnyaCache tingkat mesin, di bawah direktori aggrega di dalam direktori yang ditunjuk XDG_CACHE_HOME, atau di bawah ~/.cache/aggrega bila XDG_CACHE_HOME tidak ditetapkan. XDG_CACHE_HOME yang bukan jalur absolut tidak menempatkan cache, dan plugin yang dikompilasi kemudian hanya disimpan selama eksekusi.
HOMEmacOSCache tingkat mesin, di bawah ~/Library/Caches/aggrega.

AGGREGA_CONFIG, atau --config, langsung menunjuk file global di setiap platform dan menang atas variabel-variabel ini. Cache milik proyek tidak ditempatkan oleh satu pun dari variabel tersebut: cache itu berada di dalam proyek, di bawah artifact_cache_dir. aggrega config init menyebutkan lokasi file global dan cache tingkat mesin pada mesin tempat perintah itu dijalankan.

Boolean

Variabel boolean menerima true, false, 1, atau 0 (tidak peka huruf besar-kecil). Nilai tidak kosong lainnya merupakan galat yang terang-terangan alih-alih tebakan diam-diam — tidak seperti YAML, yes/no/on/off tidak diterima.

Rahasia

Rahasia diberikan melalui variabel lingkungan atau flag dan tidak pernah menjadi field konfigurasi.

VariabelTujuanPrioritas
AGGREGA_IDENTITY_TOKENToken identitas OIDC keyless.Flag --identity-token > AGGREGA_IDENTITY_TOKEN > OIDC ambien GitHub Actions > SIGSTORE_ID_TOKEN.
AGGREGA_REGISTRY_PASSWORDKata sandi registry untuk aggrega login non-interaktif.--password-stdin > AGGREGA_REGISTRY_PASSWORD > prompt interaktif.

SIGSTORE_ID_TOKEN diterima sebagai alias interop ekosistem sigstore untuk token identitas, dengan peringkat di bawah AGGREGA_IDENTITY_TOKEN dan endpoint ambien GitHub Actions. Variabel ini adalah variabel yang sudah ditetapkan oleh perkakas sigstore yang lebih luas.

Resolusi identitas yang sama melayani ketiga verba penandatanganan — aggrega push --sign, aggrega sign, dan aggrega deprecate. Di terminal interaktif, masing-masing memperoleh token berumur pendek melalui alur browser tanpa flag. Di GitHub Actions, masing-masing mencetak token OIDC workflow yang baru secara otomatis dari endpoint ambien runner, sehingga ekspor token tidak diperlukan. Proses non-interaktif lainnya tidak memiliki terminal maupun endpoint ambien, sehingga token harus diberikan secara eksplisit (ekspor AGGREGA_IDENTITY_TOKEN, atau berikan --identity-token). Tanpa token yang diberikan, tanpa endpoint ambien, dan tanpa terminal, penandatanganan keyless ditolak alih-alih dibiarkan menggantung.

Panduan CI (GitHub Actions)

Di GitHub Actions, CLI mendeteksi endpoint OIDC ambien runner dan mencetak token workflow yang baru untuk setiap tanda tangan secara otomatis. Berikan izin kepada job untuk mencetak token, lalu tandatangani tanpa ekspor token:

permissions:
id-token: write # allow the job to mint a workflow OIDC token
# ...
- run: aggrega push <entity> --sign

Hal yang sama berlaku untuk aggrega sign dan aggrega deprecate. Untuk menetapkan identitas tertentu alih-alih identitas yang dicetak otomatis, ekspor AGGREGA_IDENTITY_TOKEN secara eksplisit; token eksplisit (atau --identity-token) selalu menang atas endpoint ambien:

- run: |
AGGREGA_IDENTITY_TOKEN=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sigstore" | jq -r .value)
export AGGREGA_IDENTITY_TOKEN
aggrega push <entity> --sign

CI yang bukan GitHub Actions tidak memiliki endpoint ambien: ekspor AGGREGA_IDENTITY_TOKEN dari mekanisme OIDC penyedia tersebut, atau berikan --identity-token.

Untuk batch interaktif, padanannya adalah aggrega auth token, yang menjalankan alur OIDC browser satu kali dan mencetak token identitas ke stdout agar dapat diekspor dengan cara yang sama:

Terminal window
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)

Lihat aggrega-auth.md. Kedua cara memungkinkan sekumpulan pemanggilan aggrega sign menggunakan ulang satu identitas tanpa bolak-balik browser per artefak.

Utamakan --password-stdin daripada AGGREGA_REGISTRY_PASSWORD. Variabel lingkungan dapat dibaca oleh proses anak dan dapat tersimpan di shell; stdin adalah jalur yang lebih aman untuk kata sandi. Variabel lingkungan tersebut disediakan sebagai kemudahan untuk CI.

Lihat juga