Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Variáveis de ambiente

A CLI aggrega lê um conjunto fixo de variáveis de ambiente com o prefixo AGGREGA_. Cada uma substitui em tempo de execução a configuração correspondente de .aggrega-config.yaml — a camada que um job de CI ou um orquestrador que injeta segredos controla sem editar arquivos versionados —, enquanto uma flag de linha de comando continua prevalecendo sobre tudo.

Precedência

Uma variável de ambiente fica acima dos arquivos de configuração commitados — uma substituição em tempo de execução que um pipeline ou um orquestrador que injeta segredos aplica sem editar um arquivo versionado — e abaixo de uma flag de linha de comando, então um valor explícito digitado na linha de comando nunca é substituído silenciosamente pelo ambiente. Configuração traz a escala completa e a sobreposição dos arquivos abaixo.

Uma variável não definida (ou vazia) passa para a camada abaixo — ela nunca sobrescreve um valor configurado com um valor vazio. Para ver a configuração que se aplica agora, e qual camada decidiu cada configuração, execute aggrega config show --origin.

Nomenclatura

O nome de uma variável é AGGREGA_ seguido do seu caminho de configuração em upper snake case (os pontos viram sublinhados): signing.fulcio_url vira AGGREGA_SIGNING_FULCIO_URL. Um nome é encurtado por ergonomia — workspace.catalog_dirs se vincula a AGGREGA_CATALOG_DIRS, em paralelo a PATH.

As configurações por registro (registries[].*) não têm variável de ambiente: uma lista de blocos de política por host não se expressa como uma única variável, e a política de confiança e de assinatura de um registro é configuração commitada, não uma substituição vinda do ambiente. As flags situacionais, pontuais e posicionais (--dry-run, --trace, --detail, --output, --skip-verify, --release, --entity e a família lint --allow-*/--no-allow-*) também não têm variável de ambiente — são decisões de cada execução.

Configurações apoiadas no arquivo de configuração

VariávelCaminho de configuraçãoNotas
AGGREGA_DEFAULT_REGISTRYdefault_registryHost de destino/registro (hub.aggrega.ai por padrão). Escrito do jeito que default_registry é escrito em um arquivo — veja como o host de um registro é escrito —, e um valor que não esteja escrito assim é recusado quando a configuração é resolvida, indicando esta variável.
AGGREGA_OFFLINEofflineBooleano. Proíbe toda saída de rede: todo comando que buscaria, faria pull, adquiriria, faria push, assinaria ou contataria um registro se recusa de forma visível em vez de se conectar, e um build usa apenas o que a máquina já tem — seu lockfile, seu cache e seus diretórios de catálogo locais, a partir dos quais --auto-pull preenche as entidades de catálogo de um lockfile sem alcançar um registro (uma Recipe cujo chart é buscado de uma fonte remota ainda assim para offline). A descoberta então lê o índice local — o aviso de descontinuação é servido a partir do índice construído em vez de consultado ao vivo, e o nível de resolução de catálogo pelo registro remoto é pulado; a dica de plugin que um comando não reconhecido imprime lê apenas o índice local, independentemente do que esta configuração diga. A verificação do material já em cache ou fixado continua rodando — offline proíbe a busca, não a checagem local. --offline é a flag acima dela, nas duas direções: ela define a postura para uma execução, e --offline=false permite a rede para uma execução onde esta variável ou um arquivo de configuração a definiu.
AGGREGA_AUTO_PULLauto_pullBooleano. Busca automaticamente as dependências ausentes no momento do build.
AGGREGA_ARTIFACT_CACHE_DIRartifact_cache_dirDiretório do cache de conteúdo em disco, escrito em relação à raiz do workspace para que indique o mesmo diretório onde quer que o comando rode. Um valor absoluto é recusado, assim como um que indique a própria raiz do workspace — dê ao cache um subdiretório próprio.
AGGREGA_CATALOG_DIRSworkspace.catalog_dirsSeparada pelo separador de listas de caminhos do sistema operacional (: no Unix). Forneça caminhos absolutos. Substitui a lista configurada; uma Release que recebe uma lista própria em workspace.releases mantém essa lista.
AGGREGA_SIGNING_FULCIO_URLsigning.fulcio_urlURL da CA Fulcio para assinatura keyless.
AGGREGA_SIGNING_REKOR_URLsigning.rekor_urlURL do log de transparência Rekor para assinatura keyless.
AGGREGA_SIGNING_TIMESTAMP_URLsigning.timestamp_urlURL da autoridade de carimbo de tempo RFC3161 para assinatura keyless.
AGGREGA_SIGNING_KEY_PATHsigning.key_pathCaminho para uma chave PEM ECDSA P-256 mantida localmente, para assinatura com chave. Apenas um ponteiro de caminho — nunca material de chave.
AGGREGA_SIGNING_REQUIREDsigning.requiredBooleano. Exige uma assinatura para publicar e para consumir os tipos que signing.kinds abrange. Ela ativa o requisito e nunca o desativa: um arquivo de configuração que o define o mantém definido.
AGGREGA_SIGNING_KINDSsigning.kindsSeparada pelo separador de listas de caminhos do sistema operacional (: no Unix), cada entrada um tipo como seu kind: é escrito, ou all. Ela amplia os tipos que o requisito abrange e nunca os restringe; um valor que não seja um tipo assinável é recusado, indicando esta variável.
AGGREGA_SKIP_SIGNATURE_VERIFICATIONskip_signature_verificationBooleano. Desativa globalmente a verificação de assinaturas — de forma visível: todo pull registra um aviso.
AGGREGA_WORKSPACE_ROOT(forma par com --workspace-root)Raiz absoluta do workspace, que pula a descoberta — em todo comando, e para toda requisição a aggrega mcp que não indica um workspace próprio. Não é um campo de configuração; a flag prevalece quando definida. Definida vazia, é lida como não definida — exceto por aggrega mcp sobre a entrada e saída padrão com AGGREGA_BUNDLE_VERSION e sem --workspace-root, ou seja, a inicialização pelo pacote desktop com sua configuração Workspace folder vazia, que responde a toda chamada que não indica um workspace próprio com uma recusa que nomeia essa configuração. Onde ela não indica uma pasta existente, todo comando que lê seu workspace se recusa antes de fazer qualquer outra coisa, aggrega serve e um listener de aggrega mcp se recusam a iniciar, e aggrega mcp sobre a entrada e saída padrão inicia mesmo assim e responde com a recusa a toda chamada que atua nesse workspace — cada uma nomeando esta variável junto com a configuração Workspace folder do aplicativo desktop que a define, e citando o valor como foi dado.
AGGREGA_BUNDLE_VERSION(definida pelo pacote desktop)A versão do pacote desktop que iniciou aggrega mcp, que o pacote define no ambiente do servidor. Não é um campo de configuração. O servidor a lê uma vez ao iniciar e a informa ao lado da sua própria versão em describe-capabilities chamado sem argumentos, dizendo quando as duas vêm de versões diferentes; nada é recusado por uma diferença. Sua presença também marca a inicialização pelo pacote, então uma AGGREGA_WORKSPACE_ROOT vazia ao lado dela é recusada em vez de lida como não definida, como a linha acima descreve. Definida vazia, é lida como não definida.

AGGREGA_CONFIG aponta para um arquivo de configuração global explícito a ser carregado abaixo dos arquivos do próprio projeto; ela seleciona qual arquivo se aplica em vez de substituir uma única configuração. Quando não está definida, essa camada é carregada automaticamente do local padrão da plataforma — no Windows, aggrega\config.yaml dentro do diretório que a variável de ambiente APPDATA indica, e nos demais sistemas aggrega/config.yaml dentro do diretório que XDG_CONFIG_HOME indica, com ~/.config/aggrega/config.yaml como alternativa. Veja Configuração.

Onde ficam os arquivos próprios da máquina

O arquivo de configuração global e os caches de toda a máquina ficam onde cada plataforma guarda os arquivos próprios de um usuário, então aggrega também lê as variáveis que indicam esses lugares. Nenhuma delas é uma variável AGGREGA_ e nenhuma substitui uma configuração: cada uma diz onde um arquivo é procurado quando nada o indica.

VariávelLida emO que ela posiciona
APPDATAWindowsO arquivo de configuração global, em aggrega\config.yaml dentro do diretório que APPDATA indica.
LOCALAPPDATAWindowsOs caches de toda a máquina, em aggrega\cache dentro do diretório que LOCALAPPDATA indica.
XDG_CONFIG_HOME, depois HOMELinux, macOS e os outros sistemas UnixO arquivo de configuração global, em aggrega/config.yaml dentro do diretório que XDG_CONFIG_HOME indica, ou em ~/.config/aggrega/config.yaml quando XDG_CONFIG_HOME não está definida.
XDG_CACHE_HOME, depois HOMELinux e os outros sistemas UnixOs caches de toda a máquina, em um diretório aggrega dentro daquele que XDG_CACHE_HOME indica, ou em ~/.cache/aggrega quando XDG_CACHE_HOME não está definida. Uma XDG_CACHE_HOME que não seja um caminho absoluto não posiciona nenhum cache, e os plugins compilados são então mantidos apenas durante a execução.
HOMEmacOSOs caches de toda a máquina, em ~/Library/Caches/aggrega.

AGGREGA_CONFIG, ou --config, indica diretamente o arquivo global em toda plataforma e prevalece sobre estas. Os caches próprios de um projeto não são posicionados por nenhuma delas: eles ficam dentro do projeto, em artifact_cache_dir. aggrega config init diz onde ficam tanto o arquivo global quanto os caches de toda a máquina na máquina em que ele roda.

Booleanos

Uma variável booleana aceita true, false, 1 ou 0 (sem diferenciar maiúsculas de minúsculas). Qualquer outro valor não vazio é um erro visível em vez de um palpite silencioso — diferentemente do YAML, yes/no/on/off não são aceitos.

Segredos

Os segredos são fornecidos por variável de ambiente ou flag e nunca são campos de configuração.

VariávelFinalidadePrecedência
AGGREGA_IDENTITY_TOKENToken de identidade OIDC para assinatura keyless.Flag --identity-token > AGGREGA_IDENTITY_TOKEN > OIDC do ambiente do GitHub Actions > SIGSTORE_ID_TOKEN.
AGGREGA_REGISTRY_PASSWORDSenha do registro para aggrega login não interativo.--password-stdin > AGGREGA_REGISTRY_PASSWORD > prompt interativo.

SIGSTORE_ID_TOKEN é aceito como alias de interoperabilidade do ecossistema sigstore para o token de identidade, com prioridade abaixo de AGGREGA_IDENTITY_TOKEN e do endpoint do ambiente do GitHub Actions. É a variável que as ferramentas do sigstore em geral já definem.

A mesma resolução de identidade atende aos três verbos de assinatura — aggrega push --sign, aggrega sign e aggrega deprecate. Em um terminal interativo, cada um obtém um token de curta duração por meio de um fluxo no navegador, sem flags. No GitHub Actions, cada um emite automaticamente um novo token OIDC de workflow a partir do endpoint do ambiente do runner, então não é necessário exportar nenhum token. Qualquer outra execução não interativa não tem terminal nem endpoint do ambiente, então precisa fornecer o token explicitamente (exporte AGGREGA_IDENTITY_TOKEN, ou passe --identity-token). Sem token fornecido, sem endpoint do ambiente e sem terminal, a assinatura keyless é recusada em vez de ficar travada.

Orientações para CI (GitHub Actions)

No GitHub Actions, a CLI detecta o endpoint OIDC do ambiente do runner e emite automaticamente um novo token de workflow para cada assinatura. Conceda ao job a permissão de emitir um token e assine sem exportar nenhum token:

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

O mesmo vale para aggrega sign e aggrega deprecate. Para fixar uma identidade específica em vez da emitida automaticamente, exporte AGGREGA_IDENTITY_TOKEN explicitamente; um token explícito (ou --identity-token) sempre prevalece sobre o endpoint do ambiente:

- 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

Uma CI que não é o GitHub Actions não tem endpoint do ambiente: exporte AGGREGA_IDENTITY_TOKEN a partir do mecanismo OIDC desse provedor, ou passe --identity-token.

Para um lote interativo, o equivalente é aggrega auth token, que executa uma vez o fluxo OIDC no navegador e imprime o token de identidade no stdout para que ele possa ser exportado da mesma forma:

Terminal window
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)

Veja aggrega-auth.md. Qualquer um dos caminhos permite que um lote de invocações de aggrega sign reutilize uma única identidade sem uma ida ao navegador para cada artefato.

Prefira --password-stdin a AGGREGA_REGISTRY_PASSWORD. Uma variável de ambiente pode ser lida por processos filhos e pode persistir em um shell; o stdin é o caminho mais seguro para a senha. A variável de ambiente existe como uma conveniência para CI.

Veja também