Змінні середовища
CLI aggrega зчитує фіксований набір змінних середовища з префіксом AGGREGA_. Кожна з них під час виконання перевизначає відповідний параметр .aggrega-config.yaml — це рівень, яким керує завдання CI або оркестратор, що впроваджує секрети, без редагування відстежуваних файлів, — тоді як прапорець командного рядка все одно має перевагу над усім.
Пріоритет
Змінна середовища стоїть вище за закомічені файли конфігурації — це перевизначення під час виконання, яке застосовує конвеєр або оркестратор, що впроваджує секрети, не редагуючи відстежуваного файлу, — і нижче за прапорець командного рядка, тож явне значення, введене в командному рядку, ніколи не перевизначається непомітно оточенням. Конфігурація містить повну драбину пріоритетів і розшарування файлів під нею.
Змінна, яку не задано (або яка порожня), передає рішення нижчому шару — вона ніколи не перезаписує налаштоване значення порожнім. Щоб побачити конфігурацію, що діє зараз, і який шар визначив кожне налаштування, виконайте aggrega config show --origin.
Іменування
Ім’я змінної — це AGGREGA_, за яким іде її шлях у конфігурації у верхньому регістрі зі змійковим записом (крапки стають підкресленнями): signing.fulcio_url перетворюється на AGGREGA_SIGNING_FULCIO_URL. Одне ім’я скорочено для зручності — workspace.catalog_dirs прив’язано до AGGREGA_CATALOG_DIRS, за аналогією з PATH.
Налаштування окремих реєстрів (registries[].*) не мають змінної середовища: список блоків політик для окремих хостів не можна виразити однією змінною, а політика довіри й підписування реєстру — це закомічена конфігурація, а не перевизначення із середовища. Ситуативні, одноразові та позиційні прапорці (--dry-run, --trace, --detail, --output, --skip-verify, --release, --entity і сімейство lint --allow-*/--no-allow-*) також не мають змінної середовища — це рішення для окремого запуску.
Налаштування, що відповідають конфігурації
| Змінна | Шлях у конфігурації | Примітки |
|---|---|---|
AGGREGA_DEFAULT_REGISTRY | default_registry | Хост призначення/реєстру (за замовчуванням hub.aggrega.ai). Записується так само, як default_registry у файлі, — див. як записується хост реєстру, — а значення, записане інакше, відхиляється під час визначення конфігурації з зазначенням цієї змінної. |
AGGREGA_OFFLINE | offline | Булеве значення. Забороняє будь-який вихідний мережевий трафік: кожна команда, яка мала б завантажувати, витягувати, отримувати, надсилати, підписувати або звертатися до реєстру, явно відмовляє замість з’єднання, а збірка використовує лише те, що вже є на машині, — її lock-файл, її кеш і її локальні каталоги, з яких --auto-pull заповнює сутності каталогу lock-файлу без звернення до реєстру (сутність Recipe, чарт якої завантажується з віддаленого джерела, в офлайн-режимі все одно зупиняється). Пошук тоді читає локальний індекс — повідомлення про застарілість береться зі зібраного індексу, а не перевіряється наживо, а рівень визначення каталогу через віддалений реєстр пропускається; підказка щодо плагіна, яку виводить нерозпізнана команда, читає лише локальний індекс незалежно від значення цього параметра. Перевірка вже кешованих або закріплених матеріалів усе одно виконується — офлайн-режим забороняє завантаження, а не локальну перевірку. --offline — прапорець, що має вищий пріоритет, в обох напрямках: він задає режим для одного запуску, а --offline=false дозволяє мережу для одного запуску там, де її заборонила ця змінна або файл конфігурації. |
AGGREGA_AUTO_PULL | auto_pull | Булеве значення. Автоматично завантажувати відсутні залежності під час збірки. |
AGGREGA_ARTIFACT_CACHE_DIR | artifact_cache_dir | Каталог кешу вмісту на диску, записаний відносно кореня робочого простору, щоб він позначав той самий каталог, де б не запускалася команда. Абсолютне значення відхиляється, як і значення, що позначає сам корінь робочого простору, — виділіть кешу окремий підкаталог. |
AGGREGA_CATALOG_DIRS | workspace.catalog_dirs | Розділений роздільником списку шляхів ОС (: в Unix). Вказуйте абсолютні шляхи. Замінює налаштований список; сутність Release, для якої задано власний список у workspace.releases, зберігає цей список. |
AGGREGA_SIGNING_FULCIO_URL | signing.fulcio_url | URL центру сертифікації Fulcio для безключового підписування. |
AGGREGA_SIGNING_REKOR_URL | signing.rekor_url | URL журналу прозорості Rekor для безключового підписування. |
AGGREGA_SIGNING_TIMESTAMP_URL | signing.timestamp_url | URL служби позначок часу RFC3161 для безключового підписування. |
AGGREGA_SIGNING_KEY_PATH | signing.key_path | Шлях до наявного ключа ECDSA P-256 у форматі PEM для підписування ключем. Лише вказівник на шлях — ніколи не сам ключ. |
AGGREGA_SIGNING_REQUIRED | signing.required | Логічне значення. Вимагає підпису для публікації та споживання видів, які охоплює signing.kinds. Воно лише вмикає вимогу й ніколи її не вимикає: файл конфігурації, що її задає, залишає її ввімкненою. |
AGGREGA_SIGNING_KINDS | signing.kinds | Розділювач списку шляхів ОС (: в Unix), кожен запис — вид у тому написанні, у якому пишуть його kind:, або all. Розширює види, які охоплює вимога, і ніколи їх не звужує; значення, що не є видом, який можна підписати, відхиляється з указанням цієї змінної. |
AGGREGA_SKIP_SIGNATURE_VERIFICATION | skip_signature_verification | Булеве значення. Глобально вимикає перевірку підписів — явно: кожне витягування записує в журнал попередження. |
AGGREGA_WORKSPACE_ROOT | (у парі з --workspace-root) | Абсолютний корінь робочого простору без його пошуку — для кожної команди та для кожного запиту до aggrega mcp, який не називає власного робочого простору. Не є полем конфігурації; якщо задано прапорець, перевагу має він. Порожнє значення вважається незаданим — крім випадку aggrega mcp через стандартні вхід і вихід із AGGREGA_BUNDLE_VERSION і без --workspace-root, тобто запуску з настільного пакета з порожнім налаштуванням Workspace folder: тоді кожен виклик, що не називає власного робочого простору, отримує відмову з зазначенням цього налаштування. Якщо значення не вказує на наявну теку, кожна команда, що читає свій робочий простір, відмовляє до будь-яких інших дій, aggrega serve і слухач aggrega mcp відмовляються запускатися, а aggrega mcp через стандартні вхід і вихід усе одно запускається й відповідає відмовою на кожен виклик, що діє в цьому робочому просторі, — кожна відмова називає цю змінну разом із налаштуванням Workspace folder настільного застосунку, яке її задає, і наводить значення в заданому вигляді. |
AGGREGA_BUNDLE_VERSION | (задається настільним пакетом) | Версія настільного пакета, який запустив aggrega mcp; пакет задає її в середовищі сервера. Не є полем конфігурації. Сервер читає її один раз під час запуску й повідомляє поруч із власною версією у відповіді на describe-capabilities, викликаний без аргументів, зазначаючи, коли вони належать до різних випусків; через розбіжність нічого не відмовляє. Її наявність також позначає запуск із пакета, тому порожня AGGREGA_WORKSPACE_ROOT поруч із нею відхиляється, а не вважається незаданою, як описано в рядку вище. Порожнє значення вважається незаданим. |
AGGREGA_CONFIG вказує на явний глобальний файл конфігурації, що завантажується під власними файлами проєкту; вона вибирає, який файл застосовується, а не перевизначає окреме налаштування. Якщо її не задано, цей рівень автоматично завантажується з типового розташування платформи — у Windows aggrega\config.yaml у каталозі, який називає змінна середовища APPDATA, а деінде aggrega/config.yaml у каталозі, який називає XDG_CONFIG_HOME, із запасним варіантом ~/.config/aggrega/config.yaml. Див. Конфігурація.
Де розташовані власні файли машини
Глобальний файл конфігурації та загальномашинні кеші розташовані там, де кожна платформа зберігає власні файли користувача, тому aggrega також читає змінні, що називають ці місця. Жодна з них не є змінною AGGREGA_ і жодна не перевизначає налаштування: кожна вказує, де шукати файл, коли його ніщо не називає.
| Змінна | Читається в | Що розміщує |
|---|---|---|
APPDATA | Windows | Глобальний файл конфігурації — aggrega\config.yaml у каталозі, який називає APPDATA. |
LOCALAPPDATA | Windows | Загальномашинні кеші — у aggrega\cache в каталозі, який називає LOCALAPPDATA. |
XDG_CONFIG_HOME, потім HOME | Linux, macOS та інші системи Unix | Глобальний файл конфігурації — aggrega/config.yaml у каталозі, який називає XDG_CONFIG_HOME, або ~/.config/aggrega/config.yaml, якщо XDG_CONFIG_HOME не задано. |
XDG_CACHE_HOME, потім HOME | Linux та інші системи Unix | Загальномашинні кеші — у каталозі aggrega всередині того, який називає XDG_CACHE_HOME, або в ~/.cache/aggrega, якщо XDG_CACHE_HOME не задано. XDG_CACHE_HOME, що не є абсолютним шляхом, не розміщує жодного кешу, і скомпільовані плагіни тоді зберігаються лише на час запуску. |
HOME | macOS | Загальномашинні кеші — у ~/Library/Caches/aggrega. |
AGGREGA_CONFIG або --config прямо називає глобальний файл на будь-якій платформі й має перевагу над цими змінними. Власні кеші проєкту жодна з них не розміщує: вони лежать усередині проєкту, у artifact_cache_dir. aggrega config init показує, де розташовані глобальний файл і загальномашинні кеші на машині, на якій її запущено.
Булеві значення
Булева змінна приймає true, false, 1 або 0 (без урахування регістру). Будь-яке інше непорожнє значення спричиняє явну помилку, а не мовчазне припущення — на відміну від YAML, yes/no/on/off не приймаються.
Секрети
Секрети передаються через змінну середовища або прапорець і ніколи не є полями конфігурації.
| Змінна | Призначення | Пріоритет |
|---|---|---|
AGGREGA_IDENTITY_TOKEN | Токен ідентичності OIDC для безключового підписування. | Прапорець --identity-token > AGGREGA_IDENTITY_TOKEN > навколишній OIDC GitHub Actions > SIGSTORE_ID_TOKEN. |
AGGREGA_REGISTRY_PASSWORD | Пароль реєстру для неінтерактивного aggrega login. | --password-stdin > AGGREGA_REGISTRY_PASSWORD > інтерактивний запит. |
SIGSTORE_ID_TOKEN приймається як псевдонім токена ідентичності для сумісності з екосистемою sigstore і має нижчий пріоритет, ніж AGGREGA_IDENTITY_TOKEN і навколишня кінцева точка GitHub Actions. Саме цю змінну вже встановлюють ширші інструменти sigstore.
Те саме визначення ідентичності обслуговує всі три команди підписування — aggrega push --sign, aggrega sign і aggrega deprecate. В інтерактивному терміналі кожна з них отримує короткочасний токен через потік у браузері без жодних прапорців. На GitHub Actions кожна автоматично випускає свіжий OIDC-токен робочого процесу з навколишньої кінцевої точки раннера, тож експортувати токен не потрібно. Будь-який інший неінтерактивний запуск не має ні термінала, ні навколишньої кінцевої точки, тому мусить передати токен явно (експортуйте AGGREGA_IDENTITY_TOKEN або передайте --identity-token). Якщо токен не передано, навколишньої кінцевої точки немає і термінала немає, безключове підписування відхиляється, а не зависає.
Рекомендації для CI (GitHub Actions)
На GitHub Actions CLI виявляє навколишню OIDC-кінцеву точку раннера й автоматично випускає свіжий токен робочого процесу для кожного підпису. Надайте завданню дозвіл на випуск токена й підписуйте без експорту токена:
permissions: id-token: write # allow the job to mint a workflow OIDC token# ...- run: aggrega push <entity> --signТе саме стосується aggrega sign і aggrega deprecate. Щоб закріпити конкретну ідентичність замість автоматично випущеної, явно експортуйте AGGREGA_IDENTITY_TOKEN; явний токен (або --identity-token) завжди має перевагу над навколишньою кінцевою точкою:
- 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> --signCI, що не є GitHub Actions, не має навколишньої кінцевої точки: експортуйте AGGREGA_IDENTITY_TOKEN з механізму OIDC цього постачальника або передайте --identity-token.
Для інтерактивного пакета відповідником є aggrega auth token, який один раз виконує OIDC-потік у браузері й виводить токен ідентичності в stdout, щоб його можна було експортувати так само:
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)Див. aggrega-auth.md. Будь-який із цих шляхів дає змогу пакету викликів aggrega sign повторно використовувати одну ідентичність без звернення до браузера для кожного артефакту.
Віддавайте перевагу --password-stdin над AGGREGA_REGISTRY_PASSWORD. Змінну середовища можуть читати дочірні процеси, і вона може зберігатися в оболонці; stdin — безпечніший шлях для пароля. Змінна середовища існує для зручності в CI.
Див. також
- configuration.md — у якому файлі має бути параметр, а також повна модель пріоритетів, до якої входять ці змінні.
- global-flags.md —
--workspace-rootіAGGREGA_CONFIG. - aggrega-push.md і aggrega-sign.md — змінні підписування та псевдонім токена ідентичності.
- aggrega-auth.md —
aggrega auth tokenдля інтерактивного отримання токена ідентичності. - aggrega-pull.md і aggrega-build.md — змінні для офлайн-режиму, автоматичного завантаження, каталогу catalog-dir і кешу.
- ../../architecture/13-catalog-and-registry.md — параметри реєстру та підписування, які перевизначають деякі з цих змінних.