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

aggrega config

Inspecionar e gerir a configuração do workspace

Sinopse

aggrega config

Descrição

Inspect and manage the configuration Aggrega reads.
Most projects need two files.
One .aggrega-config.yaml at your project root, carrying a "workspace:" block —
that block is what marks the root — holds how this project builds: its catalog
directories, its provider bindings, which lint rules it relaxes. It is
committed, so a teammate who clones the project builds it the same way.
One global file is shared across every workspace on this machine:
~/.config/aggrega/config.yaml, or on Windows aggrega\config.yaml inside the
directory the APPDATA environment variable names. It holds what belongs to the
machine rather than to any one project: the registries you pull from and the
signature trust policy for each, how large the compiled-module store may grow,
any command extension you have installed. It loads automatically when it is
there, and nothing breaks when it is not.
Your project's file wins over the global one, an environment variable wins
over both, and a flag wins over everything.
Secrets are not configuration. A registry password or a signing identity token
is never a field in either file; it is supplied by environment variable or flag
at the moment it is needed.
Because the effective configuration is assembled rather than written anywhere,
"aggrega config show" is how you see what actually applies, and --origin is how
you find out which layer each setting came from. "aggrega config init" seeds a
working configuration, and "aggrega config capture" freezes the effective
build-critical settings into this workspace so a build does not depend on a
global file that is not committed.
Larger projects have more to work with. None of it is needed to start, and each
piece exists for the shape it solves:
More than one file inside a project. Every .aggrega-config.yaml from the
project root down to the directory you run in contributes, a nearer file
overriding a farther one. Only a file carrying "workspace:" marks the root;
one without it contributes settings without anchoring anything.
Extending a list instead of replacing it. A nearer file's list replaces the
farther one's. The companions catalog_dirs_append, governance_append,
linter_append, importer_append and providers_append concatenate onto the
resolved list at each layer instead of shadowing it.
A file your pipeline owns. .aggrega-config-append-ci.yaml may sit beside the
hand-authored file in any of those directories, so automation can overwrite
it wholesale without touching what a person wrote. It is additive only: it
removes nothing and overrides no scalar, and a scalar key written in it is
ignored and named in a warning. It never marks a root.
A relative path anchors to the file that declared it. A catalog directory, a
local plugin path, or an entry under a plugin's with.sources resolves against
the directory of the config file it was written in — not the project root,
and not the directory you ran the command from. So the same "./catalog" names
a different directory depending on which file carries it. Two settings sit
outside this rule: artifact_cache_dir is interpreted relative to the project
root wherever you run from, and AGGREGA_CATALOG_DIRS has no declaring file at
all, so supply absolute paths in it.
The other root markers. A "workspace:" block wins outright at whatever depth
it sits. Failing one, the nearest .aggrega/ directory or aggregate*.yaml,
release*.yaml or manifest*.yaml file anchors the root, in that order within a
directory; failing everything, your working directory is used.
--workspace-root skips discovery entirely.
Naming the global file. --config <path> wins over the AGGREGA_CONFIG
environment variable, which wins over the default location. Both name a file
deliberately, so a path either gives that does not exist is a loud error
rather than a silent fallback. Whichever file resolves is also the one a
config-writing command writes when it writes globally.

Subcomandos

ComandoDescrição
aggrega config captureFixar a configuração efetiva crítica para a compilação neste espaço de trabalho
aggrega config initCriar uma configuração funcional inicial com um registo e a sua política de confiança
aggrega config showMostrar a configuração efetiva e a origem de cada definição

Descrição de aggrega config capture

Write the effective build-critical configuration into this project's workspace
config file, so the workspace builds identically without relying on the
machine's global configuration.
The build-critical subset is the configuration a build participates in: a set of
plugin socket attachments and the catalog directories. By default the captured
sockets are only those that determine the
rendered output — the provider bindings and the transform-role governance attachments — since only those must
travel with the project for byte-identical output. Pass --all-plugins to also
freeze the verdict-role governance, linter, and importer sockets, which otherwise stay free to
vary by environment. Each field is written at its effective value — the value
that resolves right now with the global configuration and the workspace tree
merged together — so a binding that today comes only from the global config is
materialized into the workspace and travels with the project.
Machine-wide tooling settings, such as a registry's trust policy, are not
captured: they stay in the global config by their nature. Capture always writes
this project's workspace config file. Running it again on an unchanged
configuration rewrites the same file byte-for-byte. Run in a folder that is not
inside a workspace, with no --workspace-root naming one, it writes nothing and
exits with an error saying so.

Flags de aggrega config capture

FlagPredefiniçãoDescrição
--all-pluginsfalseCapturar todos os sockets de plugins, incluindo os controlos de governação na função de veredicto, de linter e de importador. Sem ela, a captura fixa apenas os sockets que determinam a saída renderizada (as associações de fornecedores e as anexações de governação na função de transformação).

Descrição de aggrega config init

Seed a working configuration by registering a registry and its signature trust
policy, so a fresh machine can pull and verify signed artifacts without editing
YAML by hand.
By default it registers the official hub (hub.aggrega.ai) with signatures
required and the official trusted identities. The registry's advertised trust
policy is fetched once from its own origin and pinned locally — trust-on-first-
use; when the hub is unreachable, advertises nothing, or the workspace is
offline, its built-in official baseline is written instead, so init still
produces a usable config offline. Pass --registry to seed a different registry
(for an air-gapped or private hub). Such a registry has no built-in baseline,
so seeding it while the workspace is offline is refused: init takes no
identities or key to pin by hand, so register it once while online, or add it
with "aggrega registry add --identity" or "--key".
The entry is written to the global config shared across every workspace by
default; pass --workspace to write it to this project's workspace config
instead. If the target config file already exists, init refuses rather than
overwrite it — pass --force to write anyway (the registry entry is merged into
the existing file, other settings preserved).
Before anything else, init says where things are: the configuration file it
created — or, under --force, the one already there that it wrote into — and
the directory the machine-wide caches are kept in. On Windows that directory is
aggrega\cache inside the directory the LOCALAPPDATA environment variable names;
elsewhere it is a directory named aggrega under the per-user cache directory:
~/.cache/aggrega on Linux unless XDG_CACHE_HOME names another, and
~/Library/Caches/aggrega on macOS.
A seeded configuration is a document you own and go on editing, so --dry-run does
everything init does except write: it hands the content back, creating and
modifying nothing. The answer names the file the content is for — which matters
here, because the target is the global config unless --workspace selects this
project's own. A caller that keeps its own document model puts the content there,
where it is visible before it is saved and can be amended or undone. The registry
is still contacted for its advertised trust policy, because the policy in that
content is the policy a write would have pinned.
Because a dry run does everything else init does, it refuses an existing config
file exactly as a write refuses it, and for the same reason. So its exit code
predicts the write's: if the dry run refuses, init would have refused. Pass
--force alongside it to see the merge an overwriting write would produce.
Under --dry-run standard output carries that content and nothing else, so it stays
parseable. A registry seeded with no trust policy, because it advertises none,
still produces its notice, on standard error: read that stream too, or that
configuration arrives without the advice to pin identities by hand. A pinned
policy, whether advertised or the hub's built-in baseline, is in the content
itself and produces no notice.

Flags de aggrega config init

FlagPredefiniçãoDescrição
--dry-runfalseFazer tudo exceto escrever: devolver a configuração inicial como conteúdo, nomeando o ficheiro a que se destina, e não criar nem modificar nada. Todo o restante comportamento é o da escrita, pelo que um ficheiro de configuração existente é recusado exatamente como uma escrita o recusa — passe —force juntamente com ela para obter a fusão que uma escrita com substituição produziria.
--forcefalseSubstituir um ficheiro de configuração existente. Sem ela, init recusa quando o ficheiro de destino já existe.
--globalfalseEscrever a entrada na configuração global partilhada por todos os espaços de trabalho. É a predefinição.
--registryhub.aggrega.aiAnfitrião do registo a configurar com a sua política de confiança. Por predefinição, o hub oficial.
--workspacefalseEscrever a entrada na configuração do espaço de trabalho deste projeto em vez da configuração global.

Descrição de aggrega config show

Show the configuration that applies right now.
By default it leads with the cascade of config files and environment overrides
that contributed, lowest precedence first, then prints the effective merged
configuration — the global config, the workspace-tree cascade, and any
environment override combined into what applies right now.
Pass --global or --workspace to print a single layer's own file bytes verbatim,
preserving its comments and formatting; when that layer's file does not exist it
says so rather than failing. The two are mutually exclusive.
Pass --origin to annotate each effective setting with the layer it came from —
a command-line flag, an environment variable, a config file, or the built-in
defaults, highest precedence first. A flag is named as the reader typed it, so
a setting a flag decided reports that flag as its source. A setting is
attributed to the highest-precedence layer that sets it, whatever value that
layer writes: a file restating the default is the file named, not the built-in
defaults. List and map settings are attributed as a whole. The signing
requirement is the one exception: any layer may turn it on and none can turn it
off, so it names the first layer that turns it on.

Flags de aggrega config show

FlagPredefiniçãoDescrição
--globalfalseImprimir literalmente os próprios bytes do ficheiro de configuração global, preservando os seus comentários e formatação.
--originfalseAnotar cada definição efetiva com a camada de onde veio (uma flag da linha de comandos, uma variável de ambiente, um ficheiro de configuração ou as predefinições incorporadas).
--workspacefalseImprimir literalmente os próprios bytes do ficheiro de configuração do espaço de trabalho deste projeto, preservando os seus comentários e formatação.

O que faz

Os subcomandos config criam, inspecionam e fixam a configuração que rege uma compilação. Para saber em que ficheiro pertence uma definição e como as camadas se combinam, consulte Configuração — começa pelos dois ficheiros de que a maioria dos projetos precisa e deixa o resto para depois.

config init — criar uma configuração funcional inicial

aggrega config init cria uma configuração numa máquina nova registando um registo e a sua política de confiança de assinaturas, para que os artefactos assinados sejam obtidos e verificados sem editar YAML à mão. Por predefinição, regista o hub oficial (hub.aggrega.ai) com assinaturas obrigatórias e as suas identidades oficiais de confiança. A política de confiança anunciada pelo registo é obtida uma vez a partir da sua própria origem e fixada localmente (confiança na primeira utilização); quando o hub está inacessível, não anuncia nada ou o espaço de trabalho está offline, é escrita em vez disso a base oficial incorporada, pelo que init continua a produzir uma configuração utilizável offline.

Antes de mais nada, init indica onde estão as coisas. A configuração inicial de uma máquina Linux nova começa com:

Created the global configuration file at /home/you/.config/aggrega/config.yaml
Machine-wide caches are kept in /home/you/.cache/aggrega

e a de uma máquina Windows nova com:

Created the global configuration file at C:\Users\you\AppData\Roaming\aggrega\config.yaml
Machine-wide caches are kept in C:\Users\you\AppData\Local\aggrega\cache

A primeira linha nomeia o ficheiro de configuração que init escreveu: Created quando o ficheiro não existia, e Using quando existia e --force permitiu que init escrevesse nele; com --workspace, nomeia o ficheiro de configuração do espaço de trabalho em vez do global. A segunda nomeia o diretório em que são guardadas as caches de toda a máquina — plugins compilados e as suas descrições —, que é onde cada plataforma guarda as caches de um utilizador; Que caches pertencem a este projeto e quais pertencem à máquina indica a regra por plataforma. Cada linha termina com o seu caminho e nada depois dele, para que o caminho possa ser copiado tal como está. As linhas seguintes são as do próprio registo: o que a obtenção da política de confiança encontrou e em que ficheiro o registo foi registado. Uma configuração inicial recusada não imprime nenhuma das linhas, já que não criou nada, e --dry-run também não, cuja saída padrão contém apenas o conteúdo que devolve.

  • --registry <host> configura um registo diferente — um hub isolado ou privado — em vez do oficial. Um registo destes não tem base incorporada, pelo que, quando não anuncia nada, a entrada é escrita sem política, e num espaço de trabalho offline a sua configuração é recusada (código curto E0310): a política não pode ser obtida, e init não aceita --identity nem --key para fixar uma à mão. Configure-o uma vez enquanto estiver online, ou acrescente-o com aggrega registry add e uma política fornecida pelo utilizador.
  • Se o ficheiro de destino já existir, init recusa-se a substituí-lo; --force escreve mesmo assim, fundindo a entrada do registo no ficheiro existente e preservando as outras definições.
  • --dry-run faz tudo o que init faz exceto escrever. Devolve a configuração inicial como conteúdo, sem criar nem modificar nada, e a resposta nomeia o ficheiro a que o conteúdo se destina — o que aqui importa, porque o destino é a configuração global a menos que --workspace selecione a do próprio projeto. Um chamador que mantém o seu próprio modelo de documento, como um editor, coloca o conteúdo aí, onde fica visível antes de ser guardado e pode ser alterado ou anulado.
  • Como uma execução de teste faz tudo o resto que init faz, o seu código de saída antecipa o da escrita. Recusa um ficheiro de configuração existente exatamente como uma escrita o recusa, e pela mesma razão, pelo que pode ser usada para perguntar se init teria êxito antes de avançar com a alteração. Para ver o documento que uma escrita com substituição produziria, passe --force juntamente com ela: --force --dry-run reporta a fusão e continua a não escrever nada.
  • O registo continua a ser contactado para obter a política de confiança que anuncia, porque a política no conteúdo reportado é a política que uma escrita teria fixado. Uma execução de teste faz à própria origem desse registo o mesmo pedido único não autenticado que uma escrita faz.
  • Com --dry-run, a saída padrão contém esse conteúdo e nada mais, pelo que continua a poder ser analisada. A única coisa que o conteúdo não consegue exprimir é uma ausência: quando um registo não anuncia nenhuma política de confiança e é configurado sem nenhuma, o aviso que o indica — e que diz para fixar identidades com --identity ou --key — vai para o erro padrão. Um documento de configuração sem identidades de confiança tem o mesmo aspeto quer uma política tenha sido fixada e estivesse vazia quer nenhuma tenha sido anunciada, por isso leia ambos os fluxos; um programa que descarte o erro padrão não é informado de nada. Quando o registo anuncia uma política, ou a base incorporada do hub oficial é fixada em seu lugar, a política fixada está no próprio conteúdo reportado e não é produzido nenhum aviso separado.

Uma configuração inicial é um documento que pertence ao utilizador e que ele continua a editar, e é por isso que pode ser devolvida em vez de escrita. Fixar a configuração efetiva, abaixo, produz um registo daquilo em que a configuração se resolveu — estado que o compilador guarda sobre si próprio e não conteúdo que alguém compõe — pelo que escreve sempre e não oferece --dry-run.

config show — inspecionar o que se aplica neste momento

aggrega config show reporta a configuração que se aplica neste momento. Na vista predefinida, começa pela cascata de ficheiros de configuração e substituições de ambiente que contribuíram, da menor precedência para a maior, e depois imprime a configuração efetiva fundida — a configuração global, a cascata da árvore do espaço de trabalho e qualquer sobreposição de ambiente combinadas num único resultado. Esta cascata de ficheiros carregados é onde se confirma que ficheiros e substituições de ambiente moldaram a configuração atual.

Duas vistas específicas restringem a saída:

  • --global ou --workspace imprime literalmente os bytes do ficheiro de uma única camada, com os comentários e a formatação preservados; quando o ficheiro dessa camada não existe, indica-o em vez de falhar. As duas são mutuamente exclusivas.
  • --origin anota cada definição efetiva com a camada de onde veio — uma flag da linha de comandos, uma variável de ambiente, um ficheiro de configuração ou as predefinições incorporadas, da maior precedência para a menor. Uma flag é nomeada tal como foi escrita, pelo que uma definição que --offline decidiu nesta execução reporta --offline como origem; uma variável de ambiente é nomeada após um prefixo env: e um ficheiro de configuração pelo seu caminho absoluto.

Com --origin, uma definição é atribuída à camada de maior precedência que a define, seja qual for o valor que essa camada escreve. Assim, um ficheiro de projeto que escreve default_registry: hub.aggrega.ai é nomeado para essa definição mesmo que a predefinição incorporada seja o mesmo registo, e um ficheiro de projeto que repete um valor que o ficheiro global já define é nomeado em vez do ficheiro global: em ambos os casos é o ficheiro que mantém o valor em vigor, e aquele cuja remoção muda a resposta no dia em que a predefinição ou o ficheiro abaixo dele mudar. Uma definição que nenhuma camada define reporta as predefinições incorporadas.

  • O que conta como defini-la. Um ficheiro de configuração define uma definição quando contém a chave dessa definição e, no caso de uma definição de lista, também quando contém o complemento _append da lista. Uma variável de ambiente define a sua definição quando é exportada com um valor não vazio, e uma flag quando é escrita — --offline=false define a postura tão seguramente como --offline.
  • Um ficheiro de configuração que pertence ao seu pipeline só é nomeado para as chaves para as quais é lido, que são as suas adições a listas e a política de assinatura. Uma chave que ignora, e sobre a qual avisa, nunca é reportada como origem de um valor.
  • As definições de lista e de mapa são atribuídas como um todo, à camada de maior precedência que as define; não é reportado que camada contribuiu com que entrada de uma lista.
  • O requisito de assinatura é a única exceção. Qualquer camada o pode ativar e nenhuma o pode desativar, pelo que nomeia a primeira camada que o ativa. Uma camada que escreve required: false não ativa nada, pelo que, quando nenhuma camada o ativa, a definição reporta as predefinições incorporadas.

config capture — fixar as definições críticas para a compilação

aggrega config capture escreve a configuração efetiva crítica para a compilação no ficheiro de configuração do espaço de trabalho deste projeto, para que o espaço de trabalho compile de forma idêntica sem depender da configuração global da máquina. As definições de ferramentas de toda a máquina, como a política de confiança de um registo, não são capturadas; ficam na configuração global pela sua natureza. Executá-lo novamente sobre uma configuração inalterada reescreve o mesmo ficheiro byte a byte.

O subconjunto capturado é um conjunto de anexações de sockets de plugins e os diretórios de catálogo:

  • Por predefinição, a captura fixa apenas os sockets que determinam a saída renderizada — as associações de fornecedores e as anexações de governação na função de transformação —, já que só esses têm de acompanhar o projeto para compilações idênticas byte a byte. Os diretórios de catálogo são sempre capturados.
  • --all-plugins alarga os sockets capturados para incluir também os sockets de governação na função de veredicto, de linter e de importador. Sem ela, esses três continuam livres de variar consoante o ambiente.

A captura escreve sempre e não oferece forma de devolver o conteúdo em vez disso. O que produz é um registo daquilo em que a configuração se resolveu, não um documento que alguém compõe, pelo que não há nada que um autor possa rever e alterar — reportá-lo convidaria a editar um instantâneo de uma resolução.

A captura escreve apenas dentro de um espaço de trabalho. Executada numa pasta que não esteja dentro de nenhum, sem --workspace-root nem AGGREGA_WORKSPACE_ROOT a nomear um, não escreve nada — um ficheiro de configuração escrito ali transformaria a pasta num espaço de trabalho — e termina com um erro que o indica. aggrega config init --workspace torna primeiro a pasta um espaço de trabalho.

Ver também

  • configuration.md — em que ficheiro pertence uma definição, a escala de precedência e os mecanismos a que um projeto maior recorre.
  • global-flags.md — as flags --config e --workspace-root.
  • environment-variables.md — as variáveis AGGREGA_* que substituem a configuração em tempo de execução.
  • aggrega-registry.md — gerir diretamente os registos e a sua política de confiança.
  • aggrega-cache.md — o que o diretório que artifact_cache_dir nomeia contém realmente, e porque é que uma entidade aí guardada que nenhum lockfile fixa não é encontrada por uma compilação.