Validación del registro de artefactos en la CLI

Referencia de la opción: agentengine agente validate, agentengine compilar.

Público: usuarios de CLI que ejecutan agentengine agent validate o agentengine build.

La CLI ejecuta las mismas comprobaciones del registro de artefactos de índice declarado que la validación de inicio de compilar de ECP, localmente y antes de la carga del fichero.

Comandos

Comando	Validación estricta	Advertencias secretas
`agentengine agent validate [path]`	Cuando `artifact_repositories` no está vacío	Una vez iniciada la sesión (en la medida de lo posible); `--strict` → salir 1
`agentengine build`	Igual, antes `InitArchiveBuild`	Siempre que el cliente esté disponible; no bloqueante
`agentengine build --upload-build-secrets`	Mismo	Carga primero los secretos declarados del entorno — ver a continuación

Ambos comandos leen archivos de herramientas del mismo directorio que ``agente.yaml``.

¿Qué se valida?

Siempre (esquema — `agentconfig.Validate`)

artifact_repositories forma de entrada: name, type, secret, scope, auth, npm_scope

Cuando `artifact_repositories` no está vacío (entre archivos)

Declarado name (o npm npm_scope) debe existir en las herramientas del proyecto.
La entrada de herramientas correspondiente debe tener una URL de registro HTTPS.
Las URL en las herramientas y los archivos de bloqueo cargados se escanean en busca de host no seguros para SSRF.

Modelo de inclusión voluntaria (no errores)

No artifact_repositories bloque → no hay recuperación entre archivos.
URLs HTTPS privadas en uv.lock / package-lock.json que no están declaradas → se aprueban sin credenciales de plataforma.
Las URL no seguras para SSRF en herramientas o archivos de bloqueo cargados siguen fallando con INVALID_REGISTRY_URL cuando artifact_repositories no está vacío.

Advertencias secretas (en linea)

Refleja las reglas de ámbito de ECP para la búsqueda de secretos. En la CLI, son advertencias a menos que agentengine agent validate --strict (salida 1). ECP inicio de compilar trata un secreto faltante como un fallo grave (MISSING_BUILD_SECRET antes de CodeBuild).

Código	CLI `validate`	Inicio de compilar de ECP	Significado
`MISSING_BUILD_SECRET`	Advertencia; `--strict` → salida 1	Fallo duro	No hay secreto de ASM en el alcance declarado
`SCOPE_MISMATCH_HINT`	Advertencia; `--strict` → salida 1	Fallo duro	El secreto existe en el otro ámbito
`WORKSPACE_CONTEXT_NEEDED`	Advertencia; `--strict` → salida 1	N/A (CLI necesita `agentengine init`)	Entrada con alcance de espacio de trabajo, pero sin contexto de espacio de trabajo
`SECRET_METADATA_LOOKUP_FAILED`	Advertencia; `--strict` → salida 1	Fallo grave (no reintentable); se reintenta cuando es transitorio	La lista de secretos en linea no se pudo verificar

Errores graves entre archivos

Estos fallan agentengine agent validate, agentengine build (antes de la carga) y la comprobación cruzada de inicio de compilar de ECP cuando artifact_repositories no está vacío:

Código	Significado	Qué hacer
`UNKNOWN_INDEX_NAME`	Declarado `name` (o npm `npm_scope`) no se encontró en las herramientas	Alinear `agent.yaml` con `pyproject.toml` / `.npmrc` / `publishConfig.registry`
`MISSING_REGISTRY_URL`	El nombre coincide, pero la herramienta no tiene una URL HTTPS	Agregar `url` a la configuración del índice/registro
`INVALID_REGISTRY_URL`	URL no HTTPS, credenciales incrustadas o host bloqueado	Utilice `https://`; nunca coloque tokens en las URL.

Las URL HTTPS privadas no declaradas en los archivos de bloqueo se aprueban sin credenciales de plataforma (modelo de suscripción voluntaria). Las URL no seguras para SSRF en herramientas o archivos de bloqueo cargados siguen fallando con INVALID_REGISTRY_URL cuando artifact_repositories no está vacío. Los tutoriales de configurar, la actualización de tokens de CI, la precarga de webhooks y la migración desde wheels/ de proveedor se encuentran en agent-yaml.md.

Ejemplos

Índice declarado válido (Python)

agent.yaml:

language: pythonrequired_secrets:artifact_repositories:  - name: corps-pypi    type: pypi    secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN

pyproject.toml debe contener un nombre de [[tool.uv.index]] coincidente y HTTPS url.

agentengine agent validate# ✓ ./agent.yaml valid (egress rules: 0, atlas clusters: 0, artifact repositories: 1)

Nombre declarado desconocido

agentengine agent validate# ✗ ./agent.yaml: artifact registry: UNKNOWN_INDEX_NAME: declared name "missing-index" not found in project tooling# exit 1

URL del archivo de bloqueo no declarado (pasa)

Un agente con paquetes privados en uv.lock pero **ningún** artifact_repositories bloque sale de 0 — solo autenticación gestionada por el cliente.

modo estricto

agentengine agent validate --strict# Any artifact-registry secret warning (or secret-list failure) becomes exit 1.

Subir secretos declarados antes de compilar

agentengine build --upload-build-secrets es una conveniencia de aceptación para tokens de registro de corta duración. Lee cada artifact_repositories[].secret de la variable de entorno del mismo nombre y lo PUT en el ámbito declarado antes de que se cree compilar. Nunca lee una variable de entorno que agent.yaml no declara.

export ARTIFACT_REPO_CORPS_PYPI_TOKEN="$(aws codeartifact get-authorization-token \  --domain my-domain --query authorizationToken --output text)"agentengine build --upload-build-secrets# ✓ uploaded project secret ARTIFACT_REPO_CORPS_PYPI_TOKEN (version 3)

Sin el indicador, establezca las credenciales una vez con agentengine secret set <NAME>; el indicador existe para los tokens que caducan entre compilar.

Comportamiento	Detalle
Alcance	Por entrada, desde `scope` (por defecto `project`) → Proyecto o espacio de trabajo `PUT`
Ordenando	Se ejecuta antes de la creación de compilar — ECP resuelve los secretos declarados en ASM ARNs dentro de compilar-start y hace que falle compilar si falta uno
deduplicación	El mismo secreto en el mismo ámbito y Proyecto se carga una vez, incluyendo en diferentes `--all`
Missing / empty env var	Falla antes de la carga o compilar de ese agente, enumerando todos los nombres infractores a la vez. Con `--all`, la resolución se ejecuta por espacio de trabajo, por lo que los espacios de trabajo anteriores ya pueden haber subido y compilado.
Reservado o nombre inválido	Rechazado localmente (`agent.yaml` permite nombres que la API de secretos reserva)
Autorización	El alcance del proyecto necesita `PROJECT_OWNER` (o `ORG_ADMIN`); el alcance del espacio de trabajo necesita `PROJECT_OWNER` o `AGENT_DEVELOPER`
Validación	El `artifact_repositories` de un espacio de trabajo debe pasar la validación de esquema y de archivos cruzados antes de que se carguen sus secretos, tanto en las rutas de un solo espacio de trabajo como en las de `--all`
`--all`	Subido por espacio de trabajo; un fallo afecta solo a ese espacio de trabajo

Los valores secretos nunca aparecen en stdout, registro o texto de error — una carga fallida se borra a través de la misma ruta agentengine secret set que.

Docs relacionados

artifact_repositories referencia de campo y configurar: agent-yaml.md

Volver

update

TLS corporativo