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

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

VariableChemin de configurationNotes
AGGREGA_DEFAULT_REGISTRYdefault_registryHô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_OFFLINEofflineBoolé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_PULLauto_pullBooléen. Récupère automatiquement les dépendances manquantes au moment du build.
AGGREGA_ARTIFACT_CACHE_DIRartifact_cache_dirRé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_DIRSworkspace.catalog_dirsSé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_URLsigning.fulcio_urlURL de l’autorité de certification Fulcio pour la signature keyless.
AGGREGA_SIGNING_REKOR_URLsigning.rekor_urlURL du journal de transparence Rekor pour la signature keyless.
AGGREGA_SIGNING_TIMESTAMP_URLsigning.timestamp_urlURL de l’autorité d’horodatage RFC3161 pour la signature keyless.
AGGREGA_SIGNING_KEY_PATHsigning.key_pathChemin 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_REQUIREDsigning.requiredBoolé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_KINDSsigning.kindsSé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_VERIFICATIONskip_signature_verificationBoolé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.

VariableLue sousCe qu’elle place
APPDATAWindowsLe fichier de configuration global, à aggrega\config.yaml dans le répertoire que désigne APPDATA.
LOCALAPPDATAWindowsLes caches à l’échelle de la machine, sous aggrega\cache dans le répertoire que désigne LOCALAPPDATA.
XDG_CONFIG_HOME, puis HOMELinux, macOS et les autres systèmes UnixLe 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 HOMELinux et les autres systèmes UnixLes 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.
HOMEmacOSLes 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.

VariableObjectifPriorité
AGGREGA_IDENTITY_TOKENJeton d’identité OIDC pour la signature keyless.Flag --identity-token > AGGREGA_IDENTITY_TOKEN > OIDC ambiant de GitHub Actions > SIGSTORE_ID_TOKEN.
AGGREGA_REGISTRY_PASSWORDMot 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> --sign

Il 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> --sign

Une 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 :

Terminal window
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