Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

aggrega config

Inspecter et gérer la configuration du workspace

Synopsis

aggrega config

Description

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.

Sous-commandes

CommandeDescription
aggrega config captureFige dans ce workspace la configuration effective critique pour le build
aggrega config initInitialise une configuration fonctionnelle avec un registre et sa politique de confiance
aggrega config showAffiche la configuration effective et la provenance de chaque paramètre

Description 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.

Options de aggrega config capture

OptionPar défautDescription
--all-pluginsfalseCapture tous les sockets de plugins, y compris les contrôles de gouvernance à rôle verdict, de linter et d’importer. Sans elle, capture ne fige que les sockets qui déterminent la sortie rendue (les liaisons des providers et les attachements de gouvernance à rôle transform).

Description 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.

Options de aggrega config init

OptionPar défautDescription
--dry-runfalseFait tout sauf écrire : renvoie la configuration initialisée sous forme de contenu, en nommant le fichier auquel elle est destinée, et ne crée ni ne modifie rien. Tout autre comportement est celui de l’écriture, de sorte qu’un fichier de configuration existant est refusé exactement comme une écriture le refuse — passez —force en même temps pour obtenir la fusion que produirait une écriture avec écrasement.
--forcefalseÉcrase un fichier de configuration existant. Sans elle, init refuse lorsque le fichier cible existe déjà.
--globalfalseÉcrit l’entrée dans la configuration globale partagée par tous les workspaces. C’est le comportement par défaut.
--registryhub.aggrega.aiHôte du registre à initialiser avec sa politique de confiance. Par défaut, le hub officiel.
--workspacefalseÉcrit l’entrée dans la configuration du workspace de ce projet au lieu de la configuration globale.

Description 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.

Options de aggrega config show

OptionPar défautDescription
--globalfalseAffiche tels quels les octets du fichier de configuration globale, en préservant ses commentaires et sa mise en forme.
--originfalseAnnote chaque paramètre effectif avec la couche dont il provient (une option de ligne de commande, une variable d’environnement, un fichier de configuration ou les valeurs par défaut intégrées).
--workspacefalseAffiche tels quels les octets du fichier de configuration du workspace de ce projet, en préservant ses commentaires et sa mise en forme.

Fonctionnement

Les sous-commandes config initialisent, inspectent et figent la configuration qui régit un build. Pour savoir dans quel fichier placer un paramètre et comment les couches se combinent, voir Configuration — elle commence par les deux fichiers dont la plupart des projets ont besoin et garde le reste pour la suite.

config init — initialiser une configuration fonctionnelle

aggrega config init initialise une configuration sur une machine neuve en enregistrant un registre et sa politique de confiance des signatures, de sorte que les artefacts signés sont récupérés et vérifiés sans modifier le YAML à la main. Par défaut, il enregistre le hub officiel (hub.aggrega.ai) avec signatures obligatoires et ses identités de confiance officielles. La politique de confiance annoncée par le registre est récupérée une fois depuis sa propre origine et épinglée localement (trust-on-first-use) ; lorsque le hub est injoignable, n’annonce rien ou que le workspace est hors ligne, sa base de référence officielle intégrée est écrite à la place, de sorte que init produit tout de même une configuration utilisable hors ligne.

Avant toute chose, init indique où se trouvent les éléments. L’initialisation d’une machine Linux neuve commence par :

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

et celle d’une machine Windows neuve par :

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

La première ligne nomme le fichier de configuration que init a écrit : Created lorsque le fichier n’existait pas, et Using lorsqu’il existait et que --force a permis à init d’y écrire ; avec --workspace, elle nomme le fichier de configuration du workspace au lieu du fichier global. La deuxième nomme le répertoire dans lequel sont conservés les caches à l’échelle de la machine — les plugins compilés et leurs descriptions —, c’est-à-dire là où chaque plateforme conserve les caches d’un utilisateur ; Quels caches appartiennent à ce projet, et lesquels à la machine donne la règle par plateforme. Chaque ligne se termine par son chemin et rien après, de sorte que le chemin peut être copié tel quel. Les lignes suivantes sont celles de l’enregistrement : ce qu’a trouvé la récupération de la politique de confiance, et dans quel fichier le registre a été enregistré. Une initialisation refusée n’affiche aucune des deux lignes, puisqu’elle n’a rien créé, pas plus que --dry-run, dont la sortie standard ne contient que le contenu qu’il renvoie.

  • --registry <host> initialise un registre différent — un hub isolé (air-gapped) ou privé — au lieu du registre officiel. Un tel registre n’a pas de base de référence intégrée, de sorte que lorsqu’il n’annonce rien l’entrée est écrite sans politique, et dans un workspace hors ligne son initialisation est refusée (code court E0310) : la politique ne peut pas être récupérée, et init n’accepte ni --identity ni --key pour en épingler une à la main. Initialisez-le une fois en étant en ligne, ou ajoutez-le avec aggrega registry add et une politique que vous fournissez.
  • Si le fichier cible existe déjà, init refuse plutôt que de l’écraser ; --force écrit quand même, en fusionnant l’entrée du registre dans le fichier existant et en préservant les autres paramètres.
  • --dry-run fait tout ce que fait init sauf écrire. Il renvoie la configuration initialisée sous forme de contenu, sans rien créer ni modifier, et la réponse nomme le fichier auquel le contenu est destiné — ce qui compte ici, car la cible est la configuration globale à moins que --workspace ne sélectionne celle de ce projet. Un appelant qui maintient son propre modèle de document, comme un éditeur, y place le contenu, où il est visible avant d’être enregistré et peut être modifié ou annulé.
  • Comme une exécution à blanc fait tout le reste de ce que fait init, son code de sortie prédit celui de l’écriture. Elle refuse un fichier de configuration existant exactement comme une écriture le refuse, et pour la même raison, de sorte que vous pouvez l’utiliser pour savoir si init réussirait avant de vous engager dans la modification. Pour voir le document que produirait une écriture avec écrasement, passez --force en même temps : --force --dry-run indique la fusion et n’écrit toujours rien.
  • Le registre est tout de même contacté pour sa politique de confiance annoncée, car la politique figurant dans le contenu renvoyé est celle qu’une écriture aurait épinglée. Une exécution à blanc effectue vers l’origine propre de ce registre la même requête unique non authentifiée qu’une écriture.
  • Avec --dry-run, la sortie standard contient ce contenu et rien d’autre, afin de rester analysable. La seule chose que le contenu ne peut pas exprimer est une absence : lorsqu’un registre n’annonce aucune politique de confiance et est initialisé sans politique, l’avis qui le signale — et qui vous indique d’épingler des identités avec --identity ou --key — va sur la sortie d’erreur standard. Un document de configuration sans identités de confiance a le même aspect, qu’une politique ait été épinglée et se soit trouvée vide ou qu’aucune n’ait été annoncée ; lisez donc les deux flux ; un programme qui ignore la sortie d’erreur standard n’en est pas informé. Lorsque le registre annonce bien une politique, ou que la base de référence intégrée du hub officiel est épinglée à sa place, la politique épinglée figure dans le contenu renvoyé lui-même et aucun avis distinct n’est produit.

Une configuration initialisée est un document qui vous appartient et que vous continuez à modifier, c’est pourquoi elle peut être renvoyée plutôt qu’écrite. Figer la configuration effective, ci-dessous, produit un enregistrement de ce en quoi la configuration s’est résolue — un état que le compilateur conserve sur lui-même plutôt qu’un contenu que quelqu’un compose —, c’est pourquoi cette opération écrit toujours et n’offre pas de --dry-run.

config show — inspecter ce qui s’applique en ce moment

aggrega config show indique la configuration qui s’applique en ce moment. Dans sa vue par défaut, il commence par la cascade des fichiers de configuration et des surcharges d’environnement qui y ont contribué, de la priorité la plus basse à la plus haute, puis affiche la configuration effective fusionnée — la configuration globale, la cascade de l’arborescence du workspace et toute surcouche d’environnement, combinées en un seul résultat. C’est dans cette cascade des fichiers chargés que vous confirmez quels fichiers et quelles surcharges d’environnement ont façonné la configuration actuelle.

Deux vues ciblées restreignent la sortie :

  • --global ou --workspace affiche tels quels les octets du fichier d’une seule couche, commentaires et mise en forme préservés ; lorsque le fichier de cette couche n’existe pas, il le signale plutôt que d’échouer. Les deux s’excluent mutuellement.
  • --origin annote chaque paramètre effectif avec la couche dont il provient — une option de ligne de commande, une variable d’environnement, un fichier de configuration ou les valeurs par défaut intégrées, de la priorité la plus haute à la plus basse. Une option est nommée telle que vous l’avez saisie, de sorte qu’un paramètre décidé par --offline lors de cette exécution indique --offline comme source ; une variable d’environnement est nommée derrière un préfixe env: et un fichier de configuration par son chemin absolu.

Avec --origin, un paramètre est attribué à la couche de plus haute priorité qui le définit, quelle que soit la valeur que cette couche écrit. Ainsi, un fichier de projet qui écrit default_registry: hub.aggrega.ai est nommé pour ce paramètre même si la valeur par défaut intégrée est le même registre, et un fichier de projet qui reprend une valeur que le fichier global définit déjà est nommé à la place du fichier global : dans les deux cas, c’est le fichier qui maintient la valeur en place, et celui dont la suppression change la réponse le jour où la valeur par défaut ou le fichier situé en dessous change. Un paramètre qu’aucune couche ne définit indique les valeurs par défaut intégrées.

  • Ce qui compte comme le définir. Un fichier de configuration définit un paramètre lorsqu’il contient la clé de ce paramètre, et un paramètre de type liste également lorsqu’il contient le compagnon _append de la liste. Une variable d’environnement définit son paramètre lorsqu’elle est exportée avec une valeur non vide, et une option lorsque vous la saisissez — --offline=false définit le mode tout aussi sûrement que --offline.
  • Un fichier de configuration appartenant à votre pipeline n’est nommé que pour les clés pour lesquelles il est lu, à savoir ses ajouts aux listes et la politique de signature. Une clé qu’il ignore, et à propos de laquelle il émet un avertissement, n’est jamais indiquée comme provenance d’une valeur.
  • Les paramètres de type liste et map sont attribués dans leur ensemble, à la couche de plus haute priorité qui les définit ; la couche qui a fourni telle ou telle entrée d’une liste n’est pas indiquée.
  • L’exigence de signature est la seule exception. N’importe quelle couche peut l’activer et aucune ne peut la désactiver, elle nomme donc la première couche qui l’active. Une couche qui écrit required: false n’active rien, de sorte que lorsqu’aucune couche ne l’active, le paramètre indique les valeurs par défaut intégrées.

config capture — figer les paramètres critiques pour le build

aggrega config capture écrit la configuration effective critique pour le build dans le fichier de configuration du workspace de ce projet, de sorte que le workspace se construit à l’identique sans dépendre de la configuration globale de la machine. Les paramètres d’outillage à l’échelle de la machine, comme la politique de confiance d’un registre, ne sont pas capturés ; ils restent par nature dans la configuration globale. Le relancer sur une configuration inchangée réécrit le même fichier octet pour octet.

Le sous-ensemble capturé est un ensemble d’attachements de sockets de plugins et les répertoires du catalogue :

  • Par défaut, capture ne fige que les sockets qui déterminent la sortie rendue — les liaisons des providers et les attachements de gouvernance à rôle transform —, puisque seuls ceux-ci doivent accompagner le projet pour des builds identiques octet pour octet. Les répertoires du catalogue sont toujours capturés.
  • --all-plugins étend les sockets capturés pour inclure également les sockets de gouvernance à rôle verdict, de linter et d’importer. Sans elle, ces trois-là restent libres de varier selon l’environnement.

Capture écrit toujours, et n’offre aucun moyen de recevoir le contenu à la place. Ce qu’il produit est un enregistrement de ce en quoi la configuration s’est résolue, et non un document que quelqu’un compose ; il n’y a donc rien qu’un auteur doive relire et modifier — le renvoyer inviterait à modifier un instantané d’une résolution.

La capture n’écrit que dans un workspace. Exécutée dans un dossier qui ne se trouve dans aucun, sans --workspace-root ni AGGREGA_WORKSPACE_ROOT pour en nommer un, elle n’écrit rien — un fichier de configuration écrit à cet endroit ferait du dossier un workspace — et se termine par une erreur qui le signale. aggrega config init --workspace fait d’abord du dossier un workspace.

Voir aussi

  • configuration.md — dans quel fichier placer un paramètre, l’échelle de priorité et les mécanismes auxquels recourt un projet plus important.
  • global-flags.md — les options --config et --workspace-root.
  • environment-variables.md — les variables AGGREGA_* qui surchargent la configuration à l’exécution.
  • aggrega-registry.md — gérer directement les registres et leur politique de confiance.
  • aggrega-cache.md — ce que contient réellement le répertoire que nomme artifact_cache_dir, et pourquoi une entité qui s’y trouve et qu’aucun lockfile n’épingle n’est pas trouvée par un build.