Variables d’environnement
La CLI aggrega lit un ensemble fixe de variables d’environnement préfixées par AGGREGA_. Chacune remplace à l’exécution le paramètre correspondant de .aggrega-config.yaml — la couche que contrôle un job de CI ou un orchestrateur injectant des secrets sans modifier de fichiers suivis —, tandis qu’un flag de ligne de commande l’emporte toujours sur tout.
Priorité
Une variable d’environnement se situe au-dessus des fichiers de configuration committés — un remplacement à l’exécution qu’applique un pipeline ou un orchestrateur injectant des secrets sans modifier de fichier suivi — et en dessous d’un flag de ligne de commande, de sorte qu’une valeur explicite saisie sur la ligne de commande n’est jamais remplacée silencieusement par l’environnement ambiant. Configuration présente l’échelle complète et la superposition des fichiers en dessous.
Une variable non définie (ou vide) laisse place à la couche inférieure — elle ne remplace jamais une valeur configurée par une valeur vide. Pour voir la configuration qui s’applique en ce moment, et quelle couche a décidé chaque paramètre, exécutez aggrega config show --origin.
Nommage
Un nom de variable est AGGREGA_ suivi de son chemin de configuration en upper snake case (les points deviennent des underscores) : signing.fulcio_url devient AGGREGA_SIGNING_FULCIO_URL. Un nom est raccourci par commodité — workspace.catalog_dirs correspond à AGGREGA_CATALOG_DIRS, sur le modèle de PATH.
Les paramètres propres à chaque registre (registries[].*) n’ont aucune variable d’environnement : une liste de blocs de politique par hôte ne s’exprime pas sous la forme d’une seule variable, et la politique de confiance et de signature d’un registre est une configuration committée, pas un remplacement ambiant. Les flags situationnels, ponctuels et positionnels (--dry-run, --trace, --detail, --output, --skip-verify, --release, --entity et la famille lint --allow-*/--no-allow-*) n’ont pas non plus de variable d’environnement — ce sont des décisions propres à chaque exécution.
Paramètres adossés à la configuration
| Variable | Chemin de configuration | Notes |
|---|---|---|
AGGREGA_DEFAULT_REGISTRY | default_registry | Hôte de destination/registre (hub.aggrega.ai par défaut). S’écrit comme default_registry s’écrit dans un fichier — voir comment s’écrit l’hôte d’un registre —, et une valeur qui ne s’écrit pas ainsi est refusée lorsque la configuration est résolue, avec le nom de cette variable. |
AGGREGA_OFFLINE | offline | Booléen. Interdit toute sortie réseau : chaque commande qui récupérerait, ferait un pull, acquerrait, ferait un push, signerait ou contacterait un registre refuse clairement au lieu de se connecter, et un build ne s’appuie que sur ce que la machine détient déjà — son lockfile, son cache et ses répertoires de catalogue locaux, à partir desquels --auto-pull remplit les entités de catalogue d’un lockfile sans atteindre de registre (une Recipe dont le chart est récupéré depuis une source distante s’arrête tout de même hors ligne). La découverte lit alors l’index local — l’avis de dépréciation est servi depuis l’index construit au lieu d’être sondé en direct, et le niveau de résolution du catalogue par le registre distant est ignoré ; la suggestion de plugin qu’affiche une commande non reconnue ne lit que l’index local, quelle que soit la valeur de ce paramètre. La vérification du matériel déjà en cache ou pinné s’exécute toujours — le mode hors ligne interdit la récupération, pas la vérification locale. --offline est le flag situé au-dessus, dans les deux sens : il définit la posture pour une exécution, et --offline=false autorise le réseau pour une exécution là où cette variable ou un fichier de configuration l’a activée. |
AGGREGA_AUTO_PULL | auto_pull | Booléen. Récupère automatiquement les dépendances manquantes au moment du build. |
AGGREGA_ARTIFACT_CACHE_DIR | artifact_cache_dir | Répertoire du cache de contenu sur disque, écrit relativement à la racine du workspace afin qu’il désigne le même répertoire quel que soit l’endroit où s’exécute la commande. Une valeur absolue est refusée, tout comme une valeur désignant la racine du workspace elle-même — donnez au cache son propre sous-répertoire. |
AGGREGA_CATALOG_DIRS | workspace.catalog_dirs | Séparée par le séparateur de listes de chemins du système d’exploitation (: sous Unix). Fournissez des chemins absolus. Remplace la liste configurée ; une Release dotée de sa propre liste sous workspace.releases conserve cette liste. |
AGGREGA_SIGNING_FULCIO_URL | signing.fulcio_url | URL de l’autorité de certification Fulcio pour la signature keyless. |
AGGREGA_SIGNING_REKOR_URL | signing.rekor_url | URL du journal de transparence Rekor pour la signature keyless. |
AGGREGA_SIGNING_TIMESTAMP_URL | signing.timestamp_url | URL de l’autorité d’horodatage RFC3161 pour la signature keyless. |
AGGREGA_SIGNING_KEY_PATH | signing.key_path | Chemin vers une clé PEM ECDSA P-256 détenue, pour la signature avec clé. Un simple pointeur de chemin — jamais du matériel de clé. |
AGGREGA_SIGNING_REQUIRED | signing.required | Booléen. Exige une signature pour publier et pour consommer les types que couvre signing.kinds. Elle active l’exigence et ne la désactive jamais : un fichier de configuration qui la définit la maintient définie. |
AGGREGA_SIGNING_KINDS | signing.kinds | Séparée par le séparateur de listes de chemins du système d’exploitation (: sous Unix), chaque entrée étant un type tel que s’écrit son kind:, ou all. Elle élargit les types que couvre l’exigence et ne les restreint jamais ; une valeur qui n’est pas un type signable est refusée, avec le nom de cette variable. |
AGGREGA_SKIP_SIGNATURE_VERIFICATION | skip_signature_verification | Booléen. Désactive globalement la vérification des signatures — de façon visible : chaque pull journalise un avertissement. |
AGGREGA_WORKSPACE_ROOT | (va de pair avec --workspace-root) | Racine absolue du workspace, qui ignore la découverte — sur chaque commande, et pour chaque requête à aggrega mcp qui ne désigne aucun workspace propre. Ce n’est pas un champ de configuration ; le flag l’emporte lorsqu’il est défini. Définie vide, elle est lue comme non définie — sauf par aggrega mcp sur l’entrée et la sortie standard portant AGGREGA_BUNDLE_VERSION et sans --workspace-root, c’est-à-dire le lancement par le bundle de bureau avec son paramètre Workspace folder vide, qui répond à chaque appel ne désignant aucun workspace propre par un refus nommant ce paramètre. Lorsqu’elle ne désigne aucun dossier existant, chaque commande qui lit son workspace refuse avant de faire quoi que ce soit d’autre, aggrega serve et un listener aggrega mcp refusent de démarrer, et aggrega mcp sur l’entrée et la sortie standard démarre malgré tout et répond par le refus à chaque appel qui agit dans ce workspace — chacun nommant cette variable avec le paramètre Workspace folder de l’application de bureau qui la définit, et citant la valeur telle qu’elle a été donnée. |
AGGREGA_BUNDLE_VERSION | (définie par le bundle de bureau) | La version du bundle de bureau qui a lancé aggrega mcp, que le bundle définit dans l’environnement du serveur. Ce n’est pas un champ de configuration. Le serveur la lit une fois au démarrage et la signale à côté de sa propre version sur describe-capabilities appelé sans arguments, en indiquant lorsque les deux proviennent de releases différentes ; rien n’est refusé en cas de différence. Sa présence marque aussi le lancement par le bundle, de sorte qu’un AGGREGA_WORKSPACE_ROOT vide à côté d’elle est refusé plutôt que lu comme non défini, comme l’expose la ligne ci-dessus. Définie vide, elle est lue comme non définie. |
AGGREGA_CONFIG pointe vers un fichier de configuration global explicite à charger sous les fichiers propres au projet ; elle sélectionne quel fichier s’applique plutôt que de remplacer un seul paramètre. Lorsqu’elle n’est pas définie, cette couche se charge automatiquement depuis l’emplacement par défaut de la plateforme — sous Windows, aggrega\config.yaml dans le répertoire que désigne la variable d’environnement APPDATA, et ailleurs aggrega/config.yaml dans le répertoire que désigne XDG_CONFIG_HOME, avec ~/.config/aggrega/config.yaml comme repli. Voir Configuration.
Où se trouvent les fichiers propres à la machine
Le fichier de configuration global et les caches à l’échelle de la machine se trouvent là où chaque plateforme conserve les fichiers propres d’un utilisateur, de sorte qu’aggrega lit aussi les variables qui désignent ces emplacements. Aucune d’elles n’est une variable AGGREGA_ et aucune ne remplace un paramètre : chacune indique où un fichier est cherché lorsque rien ne le désigne.
| Variable | Lue sous | Ce qu’elle place |
|---|---|---|
APPDATA | Windows | Le fichier de configuration global, à aggrega\config.yaml dans le répertoire que désigne APPDATA. |
LOCALAPPDATA | Windows | Les caches à l’échelle de la machine, sous aggrega\cache dans le répertoire que désigne LOCALAPPDATA. |
XDG_CONFIG_HOME, puis HOME | Linux, macOS et les autres systèmes Unix | Le fichier de configuration global, à aggrega/config.yaml dans le répertoire que désigne XDG_CONFIG_HOME, ou à ~/.config/aggrega/config.yaml lorsque XDG_CONFIG_HOME n’est pas définie. |
XDG_CACHE_HOME, puis HOME | Linux et les autres systèmes Unix | Les caches à l’échelle de la machine, sous un répertoire aggrega dans celui que désigne XDG_CACHE_HOME, ou sous ~/.cache/aggrega lorsque XDG_CACHE_HOME n’est pas définie. Une XDG_CACHE_HOME qui n’est pas un chemin absolu ne place aucun cache, et les plugins compilés ne sont alors conservés que pour l’exécution. |
HOME | macOS | Les caches à l’échelle de la machine, sous ~/Library/Caches/aggrega. |
AGGREGA_CONFIG, ou --config, désigne directement le fichier global sur chaque plateforme et l’emporte sur celles-ci. Les caches propres à un projet ne sont placés par aucune d’elles : ils se trouvent à l’intérieur du projet, sous artifact_cache_dir. aggrega config init indique où se trouvent à la fois le fichier global et les caches à l’échelle de la machine sur la machine où il s’exécute.
Booléens
Une variable booléenne accepte true, false, 1 ou 0 (sans distinction de casse). Toute autre valeur non vide est une erreur signalée clairement plutôt qu’une supposition silencieuse — contrairement à YAML, yes/no/on/off ne sont pas acceptés.
Secrets
Les secrets sont fournis par variable d’environnement ou par flag et ne sont jamais des champs de configuration.
| Variable | Objectif | Priorité |
|---|---|---|
AGGREGA_IDENTITY_TOKEN | Jeton d’identité OIDC pour la signature keyless. | Flag --identity-token > AGGREGA_IDENTITY_TOKEN > OIDC ambiant de GitHub Actions > SIGSTORE_ID_TOKEN. |
AGGREGA_REGISTRY_PASSWORD | Mot de passe du registre pour un aggrega login non interactif. | --password-stdin > AGGREGA_REGISTRY_PASSWORD > invite interactive. |
SIGSTORE_ID_TOKEN est pris en compte comme alias d’interopérabilité de l’écosystème sigstore pour le jeton d’identité, avec une priorité inférieure à AGGREGA_IDENTITY_TOKEN et au point de terminaison ambiant de GitHub Actions. C’est la variable que l’outillage sigstore au sens large définit déjà.
La même résolution d’identité sert les trois verbes de signature — aggrega push --sign, aggrega sign et aggrega deprecate. Dans un terminal interactif, chacun acquiert un jeton de courte durée via un flux dans le navigateur, sans aucun flag. Sur GitHub Actions, chacun émet automatiquement un nouveau jeton OIDC de workflow depuis le point de terminaison ambiant du runner, de sorte qu’aucun export de jeton n’est nécessaire. Toute autre exécution non interactive n’a ni terminal ni point de terminaison ambiant, et doit donc fournir le jeton explicitement (exportez AGGREGA_IDENTITY_TOKEN, ou passez --identity-token). Sans jeton fourni, sans point de terminaison ambiant et sans terminal, la signature keyless est refusée plutôt que laissée en suspens.
Recommandations pour la CI (GitHub Actions)
Sur GitHub Actions, la CLI détecte le point de terminaison OIDC ambiant du runner et émet automatiquement un nouveau jeton de workflow pour chaque signature. Accordez au job l’autorisation d’émettre un jeton et signez sans exporter de jeton :
permissions: id-token: write # allow the job to mint a workflow OIDC token# ...- run: aggrega push <entity> --signIl en va de même pour aggrega sign et aggrega deprecate. Pour fixer une identité précise au lieu de celle émise automatiquement, exportez explicitement AGGREGA_IDENTITY_TOKEN ; un jeton explicite (ou --identity-token) l’emporte toujours sur le point de terminaison ambiant :
- 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> --signUne CI qui n’est pas GitHub Actions n’a pas de point de terminaison ambiant : exportez AGGREGA_IDENTITY_TOKEN depuis le mécanisme OIDC de ce fournisseur, ou passez --identity-token.
Pour un lot interactif, l’équivalent est aggrega auth token, qui exécute une fois le flux OIDC dans le navigateur et affiche le jeton d’identité sur stdout afin qu’il puisse être exporté de la même façon :
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)Voir aggrega-auth.md. L’une ou l’autre voie permet à un lot d’invocations d’aggrega sign de réutiliser une seule identité sans aller-retour dans le navigateur pour chaque artefact.
Préférez --password-stdin à AGGREGA_REGISTRY_PASSWORD. Une variable d’environnement est lisible par les processus enfants et peut persister dans un shell ; stdin est la voie la plus sûre pour le mot de passe. La variable d’environnement existe par commodité pour la CI.
Voir aussi
- configuration.md — dans quel fichier un paramètre doit figurer, et le modèle de priorité complet dans lequel s’inscrivent ces variables.
- global-flags.md —
--workspace-rootetAGGREGA_CONFIG. - aggrega-push.md et aggrega-sign.md — les variables de signature et l’alias du jeton d’identité.
- aggrega-auth.md —
aggrega auth tokenpour acquérir le jeton d’identité de manière interactive. - aggrega-pull.md et aggrega-build.md — les variables de mode hors ligne, d’auto-pull, de répertoires de catalogue et de cache.
- ../../architecture/13-catalog-and-registry.md — les paramètres de registre et de signature que remplacent plusieurs de ces variables.