Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Переменные окружения

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_REGISTRYdefault_registryХост целевого реестра (по умолчанию hub.aggrega.ai). Записывается так же, как default_registry в файле, — см. как записывается хост реестра, — а значение, записанное иначе, отклоняется при разрешении конфигурации с указанием этой переменной.
AGGREGA_OFFLINEofflineЛогическое значение. Запрещает любой исходящий сетевой трафик: каждая команда, которая загрузила бы, скачала, получила, отправила, подписала что-либо или обратилась бы к реестру, вместо подключения явно отказывает, а сборка использует только то, что уже есть на машине, — её lock-файл, её кеш и её локальные каталоги, из которых --auto-pull заполняет сущности каталога из lock-файла, не обращаясь к реестру (сущность Recipe, чей чарт загружается из удалённого источника, в автономном режиме всё равно останавливается). Обнаружение в этом случае читает локальный индекс: уведомление об устаревании берётся из собранного индекса, а не запрашивается в реальном времени, а уровень разрешения каталога через удалённый реестр пропускается; подсказка о плагине, которую выводит нераспознанная команда, читает только локальный индекс, что бы ни задавала эта настройка. Проверка уже закешированных или закреплённых материалов по-прежнему выполняется: автономный режим запрещает загрузку, а не локальную проверку. --offline — флаг, стоящий над ней, в обоих направлениях: он задаёт режим на один запуск, а --offline=false разрешает сеть на один запуск там, где её запретила эта переменная или файл конфигурации.
AGGREGA_AUTO_PULLauto_pullЛогическое значение. Автоматически загружать недостающие зависимости во время сборки.
AGGREGA_ARTIFACT_CACHE_DIRartifact_cache_dirКаталог кеша содержимого на диске, записываемый относительно корня рабочего пространства, чтобы он указывал на один и тот же каталог, где бы ни выполнялась команда. Абсолютное значение отклоняется, как и значение, указывающее на сам корень рабочего пространства, — выделите кешу собственный подкаталог.
AGGREGA_CATALOG_DIRSworkspace.catalog_dirsРазделяется разделителем списка путей ОС (: в Unix). Указывайте абсолютные пути. Заменяет настроенный список; сущность Release, которой задан собственный список в workspace.releases, сохраняет этот список.
AGGREGA_SIGNING_FULCIO_URLsigning.fulcio_urlURL центра сертификации Fulcio для бесключевой подписи.
AGGREGA_SIGNING_REKOR_URLsigning.rekor_urlURL журнала прозрачности Rekor для бесключевой подписи.
AGGREGA_SIGNING_TIMESTAMP_URLsigning.timestamp_urlURL службы меток времени RFC3161 для бесключевой подписи.
AGGREGA_SIGNING_KEY_PATHsigning.key_pathПуть к хранящемуся PEM-файлу ключа ECDSA P-256 для подписи ключом. Только указатель на путь, но никогда не сам ключ.
AGGREGA_SIGNING_REQUIREDsigning.requiredЛогическое значение. Требует подпись для публикации и использования видов, которые охватывает signing.kinds. Оно только включает требование и никогда не выключает: файл конфигурации, который его задаёт, сохраняет его включённым.
AGGREGA_SIGNING_KINDSsigning.kindsРазделитель списка путей ОС (: в Unix), каждая запись — вид в том написании, в каком пишется его kind:, или all. Расширяет виды, которые охватывает требование, и никогда их не сужает; значение, не являющееся подписываемым видом, отклоняется с указанием этой переменной.
AGGREGA_SKIP_SIGNATURE_VERIFICATIONskip_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_ и ни одна не переопределяет параметр: каждая лишь говорит, где искать файл, когда его ничто не указывает.

ПеременнаяЧитается вЧто размещает
APPDATAWindowsГлобальный файл конфигурации — aggrega\config.yaml в каталоге, указанном APPDATA.
LOCALAPPDATAWindowsОбщемашинные кеши — в aggrega\cache в каталоге, указанном LOCALAPPDATA.
XDG_CONFIG_HOME, затем HOMELinux, macOS и другие системы UnixГлобальный файл конфигурации — aggrega/config.yaml в каталоге, указанном XDG_CONFIG_HOME, или ~/.config/aggrega/config.yaml, если XDG_CONFIG_HOME не задана.
XDG_CACHE_HOME, затем HOMELinux и другие системы UnixОбщемашинные кеши — в каталоге aggrega внутри каталога, указанного XDG_CACHE_HOME, или в ~/.cache/aggrega, если XDG_CACHE_HOME не задана. Значение XDG_CACHE_HOME, не являющееся абсолютным путём, не размещает кеш, и тогда скомпилированные плагины хранятся только на время запуска.
HOMEmacOSОбщемашинные кеши — в ~/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> --sign

У CI, отличного от GitHub Actions, нет окружающей конечной точки: экспортируйте AGGREGA_IDENTITY_TOKEN из механизма OIDC этого провайдера или передайте --identity-token.

Для интерактивного пакета аналогом служит aggrega auth token: команда один раз выполняет браузерный поток OIDC и выводит токен удостоверения в stdout, чтобы его можно было экспортировать тем же способом:

Terminal window
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 — настройки реестра и подписания, которые переопределяются некоторыми из этих переменных.