aggrega config
Inspecter et gérer la configuration du workspace
Synopsis
aggrega configDescription
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 catalogdirectories, its provider bindings, which lint rules it relaxes. It iscommitted, 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 thedirectory the APPDATA environment variable names. It holds what belongs to themachine rather than to any one project: the registries you pull from and thesignature trust policy for each, how large the compiled-module store may grow,any command extension you have installed. It loads automatically when it isthere, and nothing breaks when it is not.
Your project's file wins over the global one, an environment variable winsover both, and a flag wins over everything.
Secrets are not configuration. A registry password or a signing identity tokenis never a field in either file; it is supplied by environment variable or flagat 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 howyou find out which layer each setting came from. "aggrega config init" seeds aworking configuration, and "aggrega config capture" freezes the effectivebuild-critical settings into this workspace so a build does not depend on aglobal file that is not committed.
Larger projects have more to work with. None of it is needed to start, and eachpiece 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
| Commande | Description |
|---|---|
aggrega config capture | Fige dans ce workspace la configuration effective critique pour le build |
aggrega config init | Initialise une configuration fonctionnelle avec un registre et sa politique de confiance |
aggrega config show | Affiche 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 workspaceconfig file, so the workspace builds identically without relying on themachine's global configuration.
The build-critical subset is the configuration a build participates in: a set ofplugin socket attachments and the catalog directories. By default the capturedsockets are only those that determine therendered output — the provider bindings and the transform-role governance attachments — since only those musttravel with the project for byte-identical output. Pass --all-plugins to alsofreeze the verdict-role governance, linter, and importer sockets, which otherwise stay free tovary by environment. Each field is written at its effective value — the valuethat resolves right now with the global configuration and the workspace treemerged together — so a binding that today comes only from the global config ismaterialized into the workspace and travels with the project.
Machine-wide tooling settings, such as a registry's trust policy, are notcaptured: they stay in the global config by their nature. Capture always writesthis project's workspace config file. Running it again on an unchangedconfiguration rewrites the same file byte-for-byte. Run in a folder that is notinside a workspace, with no --workspace-root naming one, it writes nothing andexits with an error saying so.Options de aggrega config capture
| Option | Par défaut | Description |
|---|---|---|
--all-plugins | false | Capture 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 trustpolicy, so a fresh machine can pull and verify signed artifacts without editingYAML by hand.
By default it registers the official hub (hub.aggrega.ai) with signaturesrequired and the official trusted identities. The registry's advertised trustpolicy is fetched once from its own origin and pinned locally — trust-on-first-use; when the hub is unreachable, advertises nothing, or the workspace isoffline, its built-in official baseline is written instead, so init stillproduces 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 noidentities or key to pin by hand, so register it once while online, or add itwith "aggrega registry add --identity" or "--key".
The entry is written to the global config shared across every workspace bydefault; pass --workspace to write it to this project's workspace configinstead. If the target config file already exists, init refuses rather thanoverwrite it — pass --force to write anyway (the registry entry is merged intothe existing file, other settings preserved).
Before anything else, init says where things are: the configuration file itcreated — or, under --force, the one already there that it wrote into — andthe directory the machine-wide caches are kept in. On Windows that directory isaggrega\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 doeseverything init does except write: it hands the content back, creating andmodifying nothing. The answer names the file the content is for — which mattershere, because the target is the global config unless --workspace selects thisproject'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 registryis still contacted for its advertised trust policy, because the policy in thatcontent is the policy a write would have pinned.
Because a dry run does everything else init does, it refuses an existing configfile exactly as a write refuses it, and for the same reason. So its exit codepredicts 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 staysparseable. A registry seeded with no trust policy, because it advertises none,still produces its notice, on standard error: read that stream too, or thatconfiguration arrives without the advice to pin identities by hand. A pinnedpolicy, whether advertised or the hub's built-in baseline, is in the contentitself and produces no notice.Options de aggrega config init
| Option | Par défaut | Description |
|---|---|---|
--dry-run | false | Fait 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. |
--force | false | Écrase un fichier de configuration existant. Sans elle, init refuse lorsque le fichier cible existe déjà. |
--global | false | Écrit l’entrée dans la configuration globale partagée par tous les workspaces. C’est le comportement par défaut. |
--registry | hub.aggrega.ai | Hôte du registre à initialiser avec sa politique de confiance. Par défaut, le hub officiel. |
--workspace | false | É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 overridesthat contributed, lowest precedence first, then prints the effective mergedconfiguration — the global config, the workspace-tree cascade, and anyenvironment 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 itsays 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-indefaults, highest precedence first. A flag is named as the reader typed it, soa setting a flag decided reports that flag as its source. A setting isattributed to the highest-precedence layer that sets it, whatever value thatlayer writes: a file restating the default is the file named, not the built-indefaults. List and map settings are attributed as a whole. The signingrequirement is the one exception: any layer may turn it on and none can turn itoff, so it names the first layer that turns it on.Options de aggrega config show
| Option | Par défaut | Description |
|---|---|---|
--global | false | Affiche tels quels les octets du fichier de configuration globale, en préservant ses commentaires et sa mise en forme. |
--origin | false | 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). |
--workspace | false | Affiche 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.yamlMachine-wide caches are kept in /home/you/.cache/aggregaet celle d’une machine Windows neuve par :
Created the global configuration file at C:\Users\you\AppData\Roaming\aggrega\config.yamlMachine-wide caches are kept in C:\Users\you\AppData\Local\aggrega\cacheLa 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 courtE0310) : la politique ne peut pas être récupérée, etinitn’accepte ni--identityni--keypour en épingler une à la main. Initialisez-le une fois en étant en ligne, ou ajoutez-le avecaggrega registry addet une politique que vous fournissez.- Si le fichier cible existe déjà,
initrefuse 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-runfait tout ce que faitinitsauf é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--workspacene 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 siinitréussirait avant de vous engager dans la modification. Pour voir le document que produirait une écriture avec écrasement, passez--forceen même temps :--force --dry-runindique 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--identityou--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 :
--globalou--workspaceaffiche 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.--originannote 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--offlinelors de cette exécution indique--offlinecomme source ; une variable d’environnement est nommée derrière un préfixeenv: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
_appendde 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=falsedé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: falsen’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
--configet--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.