Validação do registro de artefatos na CLI

Referência de flag: agentengine agente validate, agentengine criar.

Público-alvo: usuários da CLI que executam agentengine agent validate ou agentengine build.

A CLI executa as mesmas verificações de registro de artefato declared-índice que a validação de início de criar do ECP, localmente e antes do upload do arquivo.

Comandos

Comando	Validação rígida	Avisos de segredo
`agentengine agent validate [path]`	Quando `artifact_repositories` não estiver vazio	Quando conectar (melhor esforço); `--strict` → sair 1
`agentengine build`	O mesmo, antes `InitArchiveBuild`	Sempre que o cliente estiver disponível; não bloqueante
`agentengine build --upload-build-secrets`	Mesmo	Carrega segredos declarados do ambiente primeiro — veja abaixo

Ambos os comandos leem arquivos de ferramentas do mesmo diretório que ``agent.yaml``.

O que é validado

Sempre (esquema — `agentconfig.Validate`)

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

Quando `artifact_repositories` não está vazio (entre arquivos)

Declarado name (ou npm npm_scope) deve existir nas ferramentas do projeto.
A entrada da ferramenta de correspondência deve ter uma URL de registro HTTPS.
URLs em ferramentas e arquivos de bloqueio carregados são verificados em busca de hospedar inseguros para SSRF.

Modelo de opt-in (não erros)

Sem o bloco artifact_repositories → sem busca entre arquivos.
URLs HTTPS privadas em uv.lock / package-lock.json que não estão declaradas → passam sem credenciais da plataforma.
URLs inseguras contra SSRF em ferramentas ou arquivos de bloqueio carregados ainda falham com INVALID_REGISTRY_URL quando artifact_repositories não está vazio.

Avisos secretos (online)

Espelha as regras de escopo do ECP para pesquisa de segredos. Na CLI, estes são avisos, a menos que agentengine agent validate --strict (saída 1). O ECP build-start trata um segredo ausente como uma falha grave (MISSING_BUILD_SECRET antes do CodeBuild).

Código	CLI `validate`	Início do criar do ECP	Significado
`MISSING_BUILD_SECRET`	Aviso; `--strict` → sair 1	Falha crítica	Nenhum segredo ASM no escopo declarado
`SCOPE_MISMATCH_HINT`	Aviso; `--strict` → sair 1	Falha crítica	O segredo existe no outro escopo
`WORKSPACE_CONTEXT_NEEDED`	Aviso; `--strict` → sair 1	N/A (CLI precisa de `agentengine init`)	Entrada com escopo de workspace, mas sem contexto de workspace
`SECRET_METADATA_LOOKUP_FAILED`	Aviso; `--strict` → sair 1	Falha crítica (não recuperável); tentado novamente quando transitório	Não foi possível verificar a lista de segredos online

Erros graves entre arquivos

Eles falham na verificação cruzada de agentengine agent validate, agentengine build (antes do upload) e início de criar do ECP quando artifact_repositories não está vazio:

Código	Significado	O que fazer
`UNKNOWN_INDEX_NAME`	`name` (ou npm `npm_scope`) declarado não encontrado nas ferramentas	Alinhe `agent.yaml` com `pyproject.toml` / `.npmrc` / `publishConfig.registry`
`MISSING_REGISTRY_URL`	O nome correspondeu, mas a ferramenta não tem uma URL HTTPS	Adicione `url` à configuração do índice/registro
`INVALID_REGISTRY_URL`	URL não HTTPS, credenciais incorporadas ou hospedar bloqueado	Use `https://`; nunca coloque tokens em URLs

URLs HTTPS privadas não declaradas em lockfiles passam sem credenciais de plataforma (modelo opt-in). URLs inseguras para SSRF em ferramentas ou lockfiles carregados ainda falham com INVALID_REGISTRY_URL quando artifact_repositories não está vazio. Passo a passo para configurar, atualização de token de CI, pré-seed de webhook e migração de wheels/ fornecido estão em agente-yaml.md.

Exemplos

Í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 deve conter um nome [[tool.uv.index]] correspondente e HTTPS url.

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

Nome declarado desconhecido

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

URL de lockfile não declarada (passa)

Um agente com pacotes privados em uv.lock, mas sem um bloco artifact_repositories, sai de 0 — apenas autenticação gerenciada pelo cliente.

modo estrito

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

Fazendo upload de segredos declarados antes de uma criar

agentengine build --upload-build-secrets é uma conveniência de opt-in para tokens de registro de curta duração. Ele lê cada artifact_repositories[].secret da variável de ambiente de mesmo nome e o PUT no escopo declarado antes que o criar seja criado. Nunca lê uma variável de ambiente que agent.yaml não 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)

Sem o sinalizador, defina as credenciais uma vez com agentengine secret set <NAME>; o sinalizador existe para tokens que expiram entre as criar.

Comportamento	Detalhes
Escopo	Por entrada, de `scope` (padrão `project`) → projeto ou workspace `PUT`
Encomenda	Executa antes da criação do criar — o ECP resolve os segredos declarados para ARNs do ASM dentro do criar-start e falha o criar se um estiver ausente
eliminação de duplicação	O mesmo segredo no mesmo escopo e projeto é carregado uma vez, inclusive em `--all`
Missing / empty env var	Falha antes do upload ou criar desse agente, listando todos os nomes ofensivos de uma vez. Com `--all`, a resolução é executada por workspace, portanto, workspaces anteriores podem já ter sido carregados e criados
Nome reservado ou inválido	Rejeitado localmente (`agent.yaml` permissões nomeiam os segredos que a API reserva)
Autorização	O escopo do projeto precisa de `PROJECT_OWNER` (ou `ORG_ADMIN`); o escopo do workspace precisa de `PROJECT_OWNER` ou `AGENT_DEVELOPER`
Validação	O `artifact_repositories` de um workspace deve passar pela validação de esquema e entre arquivos antes que qualquer um de seus segredos seja carregado, tanto no caminho de workspace único quanto no `--all`
`--all`	Carregado por workspace; uma falha afeta apenas esse workspace

Os valores secretos nunca aparecem no stdout, logs ou texto de erro — um upload com falha é limpo pelo mesmo caminho que agentengine secret set.

Docs relacionados

artifact_repositories referência de campo e configurar: agente-yaml.md

Voltar

update

tls-corporativo