Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Variables de entorno

La CLI aggrega lee un conjunto fijo de variables de entorno con el prefijo AGGREGA_. Cada una anula en tiempo de ejecución el ajuste correspondiente de .aggrega-config.yaml — la capa que controla un job de CI o un orquestador que inyecta secretos sin editar archivos versionados —, mientras que un flag de línea de comandos sigue prevaleciendo sobre todo.

Precedencia

Una variable de entorno se sitúa por encima de los archivos de configuración confirmados — una anulación en tiempo de ejecución que aplica un pipeline o un orquestador que inyecta secretos sin editar un archivo versionado — y por debajo de un flag de línea de comandos, así que un valor explícito escrito en la línea de comandos nunca queda anulado en silencio por el entorno. Configuración recoge la escala completa y la superposición de los archivos que hay debajo.

Una variable no establecida (o vacía) pasa a la capa inferior — nunca sobrescribe un valor configurado con uno vacío. Para ver la configuración que se aplica ahora mismo, y qué capa decidió cada ajuste, ejecuta aggrega config show --origin.

Nomenclatura

El nombre de una variable es AGGREGA_ seguido de su ruta de configuración en upper snake case (los puntos se convierten en guiones bajos): signing.fulcio_url se convierte en AGGREGA_SIGNING_FULCIO_URL. Un nombre se abrevia por comodidad — workspace.catalog_dirs se asocia a AGGREGA_CATALOG_DIRS, en paralelo con PATH.

Los ajustes por registro (registries[].*) no tienen variable de entorno: una lista de bloques de política por host no se expresa como una sola variable, y la política de confianza y de firma de un registro es configuración confirmada, no una anulación del entorno. Los flags situacionales, puntuales y posicionales (--dry-run, --trace, --detail, --output, --skip-verify, --release, --entity y la familia lint --allow-*/--no-allow-*) tampoco tienen variable de entorno — son decisiones de cada ejecución.

Ajustes respaldados por la configuración

VariableRuta de configuraciónNotas
AGGREGA_DEFAULT_REGISTRYdefault_registryHost de destino/registro (hub.aggrega.ai de forma predeterminada). Se escribe como se escribe default_registry en un archivo — consulta cómo se escribe el host de un registro —, y un valor que no se escribe así se rechaza cuando se resuelve la configuración, indicando esta variable.
AGGREGA_OFFLINEofflineBooleano. Prohíbe toda salida de red: cada comando que obtendría, haría pull, adquiriría, haría push, firmaría o contactaría con un registro se niega de forma visible en lugar de conectarse, y una compilación usa solo lo que la máquina ya tiene — su lockfile, su caché y sus directorios de catálogo locales, desde los que --auto-pull rellena las entidades de catálogo de un lockfile sin alcanzar un registro (una Recipe cuyo chart se obtiene de una fuente remota se detiene igualmente sin conexión). El descubrimiento lee entonces el índice local — el aviso de obsolescencia se sirve desde el índice construido en lugar de consultarse en vivo, y se omite el nivel de resolución del catálogo desde el registro remoto; la sugerencia de plugin que imprime un comando no reconocido lee solo el índice local, diga lo que diga esta opción. La verificación del material ya en caché o fijado sigue ejecutándose — el modo sin conexión prohíbe la obtención, no la comprobación local. --offline es el flag que está por encima, en ambas direcciones: establece la postura para una ejecución, y --offline=false permite la red para una ejecución donde esta variable o un archivo de configuración la ha establecido.
AGGREGA_AUTO_PULLauto_pullBooleano. Obtiene automáticamente las dependencias que faltan al compilar.
AGGREGA_ARTIFACT_CACHE_DIRartifact_cache_dirDirectorio de la caché de contenido en disco, escrito de forma relativa a la raíz del workspace para que indique el mismo directorio dondequiera que se ejecute el comando. Un valor absoluto se rechaza, igual que uno que indique la propia raíz del workspace — da a la caché un subdirectorio propio.
AGGREGA_CATALOG_DIRSworkspace.catalog_dirsSeparada por el separador de listas de rutas del sistema operativo (: en Unix). Proporciona rutas absolutas. Sustituye la lista configurada; una Release a la que se da una lista propia en workspace.releases conserva esa lista.
AGGREGA_SIGNING_FULCIO_URLsigning.fulcio_urlURL de la CA de Fulcio para la firma sin claves.
AGGREGA_SIGNING_REKOR_URLsigning.rekor_urlURL del registro de transparencia de Rekor para la firma sin claves.
AGGREGA_SIGNING_TIMESTAMP_URLsigning.timestamp_urlURL de la autoridad de sellado de tiempo RFC3161 para la firma sin claves.
AGGREGA_SIGNING_KEY_PATHsigning.key_pathRuta a una clave PEM ECDSA P-256 en posesión, para la firma con clave. Solo un puntero a una ruta — nunca material de clave.
AGGREGA_SIGNING_REQUIREDsigning.requiredBooleano. Exige una firma para publicar y para consumir los tipos que cubre signing.kinds. Activa el requisito y nunca lo desactiva: un archivo de configuración que lo establece lo mantiene establecido.
AGGREGA_SIGNING_KINDSsigning.kindsSeparada por el separador de listas de rutas del sistema operativo (: en Unix), cada entrada un tipo tal como se escribe su kind:, o all. Amplía los tipos que cubre el requisito y nunca los reduce; un valor que no es un tipo firmable se rechaza, indicando esta variable.
AGGREGA_SKIP_SIGNATURE_VERIFICATIONskip_signature_verificationBooleano. Desactiva globalmente la verificación de firmas — de forma visible: cada pull registra una advertencia.
AGGREGA_WORKSPACE_ROOT(se combina con --workspace-root)Raíz absoluta del workspace, que omite el descubrimiento — en cada comando, y para cada solicitud a aggrega mcp que no indica un workspace propio. No es un campo de configuración; el flag prevalece cuando está establecido. Establecida vacía, se lee como no establecida — salvo por aggrega mcp sobre la entrada y salida estándar con AGGREGA_BUNDLE_VERSION y sin --workspace-root, es decir, el inicio por el paquete de escritorio con su ajuste Workspace folder vacío, que responde a cada llamada que no indica un workspace propio con un rechazo que nombra ese ajuste. Donde no indica una carpeta existente, cada comando que lee su workspace se niega antes de hacer cualquier otra cosa, aggrega serve y un listener de aggrega mcp se niegan a arrancar, y aggrega mcp sobre la entrada y salida estándar arranca de todos modos y responde con el rechazo a cada llamada que actúa en ese workspace — cada uno nombrando esta variable junto con el ajuste Workspace folder de la aplicación de escritorio que la establece, y citando el valor tal como se dio.
AGGREGA_BUNDLE_VERSION(establecida por el paquete de escritorio)La versión del paquete de escritorio que inició aggrega mcp, que el paquete establece en el entorno del servidor. No es un campo de configuración. El servidor la lee una vez al arrancar y la informa junto a su propia versión en describe-capabilities llamado sin argumentos, indicando cuándo las dos proceden de versiones distintas; nada se rechaza por una diferencia. Su presencia también marca el inicio por el paquete, así que un AGGREGA_WORKSPACE_ROOT vacío junto a ella se rechaza en lugar de leerse como no establecido, como expone la fila anterior. Establecida vacía, se lee como no establecida.

AGGREGA_CONFIG apunta a un archivo de configuración global explícito que se carga por debajo de los archivos propios del proyecto; selecciona qué archivo se aplica en lugar de anular un solo ajuste. Cuando no está establecida, esa capa se carga automáticamente desde la ubicación predeterminada de la plataforma — en Windows, aggrega\config.yaml dentro del directorio que indica la variable de entorno APPDATA, y en otros sistemas aggrega/config.yaml dentro del directorio que indica XDG_CONFIG_HOME, con ~/.config/aggrega/config.yaml como alternativa. Consulta Configuración.

Dónde están los archivos propios de la máquina

El archivo de configuración global y las cachés de toda la máquina están donde cada plataforma guarda los archivos propios de un usuario, así que aggrega también lee las variables que indican esos lugares. Ninguna de ellas es una variable AGGREGA_ y ninguna anula un ajuste: cada una indica dónde se busca un archivo cuando nada lo indica.

VariableSe lee enQué ubica
APPDATAWindowsEl archivo de configuración global, en aggrega\config.yaml dentro del directorio que indica APPDATA.
LOCALAPPDATAWindowsLas cachés de toda la máquina, en aggrega\cache dentro del directorio que indica LOCALAPPDATA.
XDG_CONFIG_HOME, luego HOMELinux, macOS y los demás sistemas UnixEl archivo de configuración global, en aggrega/config.yaml dentro del directorio que indica XDG_CONFIG_HOME, o en ~/.config/aggrega/config.yaml cuando XDG_CONFIG_HOME no está establecida.
XDG_CACHE_HOME, luego HOMELinux y los demás sistemas UnixLas cachés de toda la máquina, en un directorio aggrega dentro del que indica XDG_CACHE_HOME, o en ~/.cache/aggrega cuando XDG_CACHE_HOME no está establecida. Una XDG_CACHE_HOME que no es una ruta absoluta no ubica ninguna caché, y los plugins compilados se conservan entonces solo durante la ejecución.
HOMEmacOSLas cachés de toda la máquina, en ~/Library/Caches/aggrega.

AGGREGA_CONFIG, o --config, indica directamente el archivo global en cada plataforma y prevalece sobre estas. Las cachés propias de un proyecto no las ubica ninguna de ellas: están dentro del proyecto, en artifact_cache_dir. aggrega config init indica dónde están tanto el archivo global como las cachés de toda la máquina en la máquina en la que se ejecuta.

Booleanos

Una variable booleana acepta true, false, 1 o 0 (sin distinguir mayúsculas de minúsculas). Cualquier otro valor no vacío es un error visible en lugar de una suposición silenciosa — a diferencia de YAML, no se aceptan yes/no/on/off.

Secretos

Los secretos se suministran mediante variable de entorno o flag y nunca son campos de configuración.

VariablePropósitoPrecedencia
AGGREGA_IDENTITY_TOKENToken de identidad OIDC para la firma sin claves.Flag --identity-token > AGGREGA_IDENTITY_TOKEN > OIDC del entorno de GitHub Actions > SIGSTORE_ID_TOKEN.
AGGREGA_REGISTRY_PASSWORDContraseña del registro para aggrega login no interactivo.--password-stdin > AGGREGA_REGISTRY_PASSWORD > solicitud interactiva.

SIGSTORE_ID_TOKEN se acepta como alias de interoperabilidad del ecosistema sigstore para el token de identidad, con menor prioridad que AGGREGA_IDENTITY_TOKEN y el endpoint del entorno de GitHub Actions. Es la variable que las herramientas de sigstore en general ya establecen.

La misma resolución de identidad sirve a los tres verbos de firma — aggrega push --sign, aggrega sign y aggrega deprecate. En un terminal interactivo, cada uno adquiere un token de corta duración mediante un flujo en el navegador, sin flags. En GitHub Actions, cada uno emite automáticamente un token OIDC de workflow nuevo desde el endpoint del entorno del runner, así que no hace falta exportar ningún token. Cualquier otra ejecución no interactiva no tiene ni terminal ni endpoint del entorno, así que debe suministrar el token explícitamente (exporta AGGREGA_IDENTITY_TOKEN, o pasa --identity-token). Sin token suministrado, sin endpoint del entorno y sin terminal, la firma sin claves se rechaza en lugar de quedarse bloqueada.

Orientación para CI (GitHub Actions)

En GitHub Actions, la CLI detecta el endpoint OIDC del entorno del runner y emite automáticamente un token de workflow nuevo para cada firma. Concede al job permiso para emitir un token y firma sin exportar ningún token:

permissions:
id-token: write # allow the job to mint a workflow OIDC token
# ...
- run: aggrega push <entity> --sign

Lo mismo vale para aggrega sign y aggrega deprecate. Para fijar una identidad concreta en lugar de la emitida automáticamente, exporta AGGREGA_IDENTITY_TOKEN explícitamente; un token explícito (o --identity-token) siempre prevalece sobre el endpoint del entorno:

- 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

Una CI que no es GitHub Actions no tiene endpoint del entorno: exporta AGGREGA_IDENTITY_TOKEN desde el mecanismo OIDC de ese proveedor, o pasa --identity-token.

Para un lote interactivo, el equivalente es aggrega auth token, que ejecuta una vez el flujo OIDC en el navegador e imprime el token de identidad en stdout para que pueda exportarse del mismo modo:

Terminal window
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)

Consulta aggrega-auth.md. Cualquiera de los dos caminos permite que un lote de invocaciones de aggrega sign reutilice una sola identidad sin pasar por el navegador para cada artefacto.

Prefiere --password-stdin a AGGREGA_REGISTRY_PASSWORD. Una variable de entorno es legible por los procesos hijos y puede persistir en un shell; stdin es la vía más segura para la contraseña. La variable de entorno existe como comodidad para CI.

Véase también