Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler 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 a definição correspondente de .aggrega-config.yaml em tempo de execução — a camada que um job de CI ou um orquestrador que injeta segredos controla sem editar ficheiros rastreados —, enquanto uma flag da linha de comandos continua a prevalecer sobre tudo.

Precedência

Uma variável de ambiente fica acima dos ficheiros de configuração incluídos no controlo de versões — uma substituição em tempo de execução que um pipeline ou um orquestrador que injeta segredos aplica sem editar um ficheiro rastreado — e abaixo de uma flag da linha de comandos, para que um valor explícito escrito na linha de comandos nunca seja silenciosamente substituído pelo ambiente. Configuração apresenta a escala completa e a sobreposição dos ficheiros por baixo.

Uma variável que não está definida (ou que está vazia) passa para a camada abaixo — nunca substitui um valor configurado por um valor em branco. Para ver a configuração que se aplica neste momento, e que camada decidiu cada definição, execute aggrega config show --origin.

Nomenclatura

O nome de uma variável é AGGREGA_ seguido do seu caminho de configuração em maiúsculas com underscores (os pontos passam a underscores): signing.fulcio_url passa a AGGREGA_SIGNING_FULCIO_URL. Um nome é encurtado por ergonomia — workspace.catalog_dirs associa-se a AGGREGA_CATALOG_DIRS, em paralelo com PATH.

As definições por registo (registries[].*) não têm variável de ambiente: uma lista de blocos de política por anfitrião não se exprime como uma única variável, e a política de confiança e de assinatura de um registo é configuração incluída no controlo de versões, não uma substituição 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 por execução.

Definições suportadas por configuração

VariávelCaminho de configuraçãoNotas
AGGREGA_DEFAULT_REGISTRYdefault_registryAnfitrião de destino/registo (hub.aggrega.ai por predefinição). Escrito da forma como default_registry é escrito num ficheiro — consulte como se escreve um anfitrião de registo — e um valor que não o seja é recusado quando a configuração é resolvida, nomeando esta variável.
AGGREGA_OFFLINEofflineBooleano. Proíbe toda a saída de rede: todos os comandos que obteriam, fariam pull, adquiririam, fariam push, assinariam ou contactariam um registo recusam ruidosamente em vez de estabelecer ligação, e uma compilação recorre apenas ao que a máquina já contém — o seu lockfile, a sua cache e os seus diretórios de catálogo locais, a partir dos quais --auto-pull preenche as entidades de catálogo de um lockfile sem chegar a um registo (uma Recipe cujo chart é obtido de uma origem remota continua a parar em modo offline). A descoberta lê então o índice local — o aviso de descontinuação é servido a partir do índice construído em vez de ser sondado em tempo real, e o nível de resolução de catálogo de registo remoto é ignorado; a sugestão de plugin que um comando não reconhecido imprime lê apenas o índice local, seja qual for o valor desta definição. A verificação de material já em cache ou fixado continua a correr — o modo offline proíbe a obtenção, não a verificação local. --offline é a flag acima dela, em ambos os sentidos: define a postura para uma execução, e --offline=false permite a rede para uma execução em que esta variável ou um ficheiro de configuração a tenha definido.
AGGREGA_AUTO_PULLauto_pullBooleano. Obtém automaticamente as dependências em falta no momento da compilação.
AGGREGA_ARTIFACT_CACHE_DIRartifact_cache_dirDiretório da cache de conteúdo em disco, escrito em relação à raiz do espaço de trabalho para que nomeie o mesmo diretório seja de onde for que o comando corre. Um valor absoluto é recusado, tal como um que nomeie a própria raiz do espaço de trabalho — dê à cache o seu próprio subdiretório.
AGGREGA_CATALOG_DIRSworkspace.catalog_dirsSeparado pelo separador de listas de caminhos do sistema operativo (: em Unix). Forneça caminhos absolutos. Substitui a lista configurada; uma Release a que é dada uma lista própria em workspace.releases mantém essa lista.
AGGREGA_SIGNING_FULCIO_URLsigning.fulcio_urlURL da CA Fulcio sem chave.
AGGREGA_SIGNING_REKOR_URLsigning.rekor_urlURL do registo de transparência Rekor sem chave.
AGGREGA_SIGNING_TIMESTAMP_URLsigning.timestamp_urlURL da autoridade de carimbo temporal RFC3161 sem chave.
AGGREGA_SIGNING_KEY_PATHsigning.key_pathCaminho para um PEM de chave ECDSA P-256 detida 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. Ativa o requisito e nunca o desativa: um ficheiro de configuração que o define mantém-no definido.
AGGREGA_SIGNING_KINDSsigning.kindsSeparada pelo separador de listas de caminhos do sistema operativo (: em Unix), sendo cada entrada um tipo tal como o seu kind: é escrito, ou all. Alarga 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 ruidosa: cada pull regista um aviso.
AGGREGA_WORKSPACE_ROOT(emparelha com --workspace-root)Raiz absoluta do espaço de trabalho, saltando a descoberta — em todos os comandos, e em todos os pedidos a aggrega mcp que não nomeiam um espaço de trabalho próprio. Não é um campo de configuração; a flag prevalece quando definida. Definida como vazia, é lida como não definida — exceto por aggrega mcp através da entrada e da saída padrão com AGGREGA_BUNDLE_VERSION e sem --workspace-root, o lançamento do pacote de ambiente de trabalho com a sua definição Workspace folder vazia, que responde a todas as chamadas que não nomeiam um espaço de trabalho próprio com uma recusa que nomeia essa definição. Quando não nomeia nenhuma pasta existente, todos os comandos que leem o seu espaço de trabalho recusam antes de fazer qualquer outra coisa, aggrega serve e um listener de aggrega mcp recusam-se a arrancar, e aggrega mcp através da entrada e da saída padrão arranca na mesma e responde a todas as chamadas que atuam nesse espaço de trabalho com a recusa — cada uma nomeando esta variável juntamente com a definição Workspace folder da aplicação de ambiente de trabalho que a define, e citando o valor tal como foi dado.
AGGREGA_BUNDLE_VERSION(definida pelo pacote de ambiente de trabalho)A versão do pacote de ambiente de trabalho que lançou aggrega mcp, que o pacote define no ambiente do servidor. Não é um campo de configuração. O servidor lê-a uma vez quando arranca e reporta-a ao lado da sua própria versão em describe-capabilities chamado sem argumentos, indicando quando as duas provêm de versões diferentes; nada recusa por causa de uma diferença. A sua presença também marca o lançamento do pacote, pelo que um AGGREGA_WORKSPACE_ROOT vazio ao lado dela é recusado em vez de ser lido como não definido, como expõe a linha acima. Definida como vazia, é lida como não definida.

AGGREGA_CONFIG aponta para um ficheiro de configuração global explícito a carregar por baixo dos próprios ficheiros do projeto; seleciona que ficheiro se aplica em vez de substituir uma única definição. Quando não está definida, essa camada é carregada automaticamente a partir da localização predefinida da plataforma — no Windows, aggrega\config.yaml dentro do diretório que a variável de ambiente APPDATA nomeia, e noutros sistemas, aggrega/config.yaml dentro do diretório que XDG_CONFIG_HOME nomeia, recorrendo a ~/.config/aggrega/config.yaml. Consulte Configuração.

Onde estão os ficheiros próprios da máquina

O ficheiro de configuração global e as caches de toda a máquina estão onde cada plataforma guarda os ficheiros próprios de um utilizador, pelo que aggrega também lê as variáveis que nomeiam esses locais. Nenhuma delas é uma variável AGGREGA_ e nenhuma substitui uma definição: cada uma diz onde um ficheiro é procurado quando nada o nomeia.

VariávelLida emO que localiza
APPDATAWindowsO ficheiro de configuração global, em aggrega\config.yaml dentro do diretório que APPDATA nomeia.
LOCALAPPDATAWindowsAs caches de toda a máquina, em aggrega\cache dentro do diretório que LOCALAPPDATA nomeia.
XDG_CONFIG_HOME, depois HOMELinux, macOS e os outros sistemas UnixO ficheiro de configuração global, em aggrega/config.yaml dentro do diretório que XDG_CONFIG_HOME nomeia, ou em ~/.config/aggrega/config.yaml quando XDG_CONFIG_HOME não está definida.
XDG_CACHE_HOME, depois HOMELinux e os outros sistemas UnixAs caches de toda a máquina, num diretório aggrega dentro daquele que XDG_CACHE_HOME nomeia, 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 localiza nenhuma cache, e os plugins compilados são então mantidos apenas durante a execução.
HOMEmacOSAs caches de toda a máquina, em ~/Library/Caches/aggrega.

AGGREGA_CONFIG, ou --config, nomeia o ficheiro global diretamente em todas as plataformas e prevalece sobre estas. As caches próprias de um projeto não são localizadas por nenhuma delas: estão dentro do projeto, em artifact_cache_dir. aggrega config init indica onde estão tanto o ficheiro global como as caches de toda a máquina na máquina em que corre.

Booleanos

Uma variável booleana aceita true, false, 1 ou 0 (sem distinção entre maiúsculas e minúsculas). Qualquer outro valor não vazio é um erro ruidoso e não uma suposição silenciosa — ao contrário do YAML, yes/no/on/off não são aceites.

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 sem chave.Flag --identity-token > AGGREGA_IDENTITY_TOKEN > OIDC ambiente do GitHub Actions > SIGSTORE_ID_TOKEN.
AGGREGA_REGISTRY_PASSWORDPalavra-passe do registo para aggrega login não interativo.--password-stdin > AGGREGA_REGISTRY_PASSWORD > pedido interativo.

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

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

Orientações para CI (GitHub Actions)

No GitHub Actions, a CLI deteta o endpoint OIDC ambiente do runner e emite automaticamente um token de workflow novo para cada assinatura. Conceda ao job permissão para 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 se aplica a 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) prevalece sempre sobre o endpoint 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 seja o GitHub Actions não tem endpoint ambiente: exporte AGGREGA_IDENTITY_TOKEN a partir do mecanismo OIDC desse fornecedor, ou passe --identity-token.

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

Terminal window
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)

Consulte aggrega-auth.md. Qualquer um dos caminhos permite que um lote de invocações de aggrega sign reutilize uma identidade sem uma ida e volta pelo navegador por artefacto.

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

Ver também