Artifact registry validation in the CLI (AP-3985)

Flag reference: agentengine agent validate, agentengine build.

Audience: CLI users running agentengine agent validate or agentengine build. For ECP build-start hook placement, secret metadata lookup, and GitHub/archive file loading, see operator documentation at docs/executor/artifact-registry-validation.md in the agentic-platform monorepo (not shipped in the client-libraries mirror).

The Agentic CLI runs the same declared-index artifact registry checks as ECP build-start validation, locally and before archive upload. Shared logic lives in client-libraries/agent-config/agentconfig/ (ValidateArtifactRegistry, LoadProjectFilesFromDir).

Commands

Command	Hard validation	Secret warnings
`agentengine agent validate [path]`	When `artifact_repositories` is non-empty	When logged in (best-effort); `--strict` → exit 1
`agentengine build`	Same, before `InitArchiveBuild`	Always when client is available; non-blocking
`agentengine build --upload-build-secrets`	Same	Uploads declared secrets from the environment first — see below

Both commands read tooling files from the same directory as ``agent.yaml`` (not the monorepo root unless the manifest lives there).

What is validated

Always (schema — `agentconfig.Validate`)

artifact_repositories entry shape: name, type, secret, scope, auth, npm_scope

When `artifact_repositories` is non-empty (cross-file)

Declared name (or npm npm_scope) must exist in project tooling.
Matching tooling entry must have an HTTPS registry URL.
URLs in tooling and loaded lockfiles are scanned for SSRF-unsafe hosts.

Opt-in model (not errors)

No artifact_repositories block → no cross-file fetch.
Private HTTPS URLs in uv.lock / package-lock.json that are not declared → pass without platform creds.
SSRF-unsafe URLs in tooling or loaded lockfiles still fail with INVALID_REGISTRY_URL when artifact_repositories is non-empty.

Secret warnings (online)

Mirrors ECP AP-3980 scope rules using ListSecrets / ListWorkspaceSecrets. In the CLI these are warnings unless agentengine agent validate --strict (exit 1). ECP build-start treats a missing secret as a hard failure (MISSING_BUILD_SECRET before CodeBuild).

Code	CLI `validate`	ECP build start	Meaning
`MISSING_BUILD_SECRET`	Warning; `--strict` → exit 1	Hard fail	No ASM secret at declared scope
`SCOPE_MISMATCH_HINT`	Warning; `--strict` → exit 1	Hard fail	Secret exists at the other scope
`WORKSPACE_CONTEXT_NEEDED`	Warning; `--strict` → exit 1	N/A (CLI needs `agentengine init`)	Workspace-scoped entry but no workspace context
`SECRET_METADATA_LOOKUP_FAILED`	Warning; `--strict` → exit 1	Hard fail (non-retryable); retried when transient	Online secret list could not be verified

Cross-file hard errors

These fail agentengine agent validate, agentengine build (before upload), and ECP build-start cross-check when artifact_repositories is non-empty:

Code	Meaning	What to do
`UNKNOWN_INDEX_NAME`	Declared `name` (or npm `npm_scope`) not found in tooling	Align `agent.yaml` with `pyproject.toml` / `.npmrc` / `publishConfig.registry`
`MISSING_REGISTRY_URL`	Name matched but tooling has no HTTPS URL	Add `url` to the index/registry config
`INVALID_REGISTRY_URL`	Non-HTTPS URL, embedded credentials, or blocked host	Use `https://`; never put tokens in URLs

Undeclared private HTTPS URLs in lockfiles pass without platform creds (opt-in model). SSRF-unsafe URLs in tooling or loaded lockfiles still fail with INVALID_REGISTRY_URL when artifact_repositories is non-empty. Setup walkthroughs, CI token refresh, webhook pre-seed, and migration from vendored wheels/ are in agent-yaml.md.

Examples

Valid declared index (Python)

agent.yaml:

language: python
required_secrets:
artifact_repositories:
  - name: corps-pypi
    type: pypi
    secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN

pyproject.toml must contain a matching [[tool.uv.index]] name and HTTPS url.

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

Unknown declared name

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

Undeclared lockfile URL (passes)

An agent with private packages in uv.lock but no artifact_repositories block exits 0 — customer-managed auth only.

Strict mode

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

Uploading declared secrets before a build (AP-3986)

agentengine build --upload-build-secrets is an opt-in convenience for short-lived registry tokens. It reads each artifact_repositories[].secret from the environment variable of the same name and PUT s it at the declared scope before the build is created. It never reads an environment variable that agent.yaml does not declare.

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)

Without the flag, set credentials once with agentengine secret set <NAME>; the flag exists for tokens that expire between builds.

Behavior	Detail
Scope	Per entry, from `scope` (default `project`) → project or workspace `PUT`
Ordering	Runs before build creation — ECP resolves declared secrets to ASM ARNs inside build-start and fails the build if one is absent
Deduplication	Same secret at the same scope and project is uploaded once, including across `--all`
Missing / empty env var	Fails before that agent’s upload or build, listing every offending name at once. With `--all`, resolution runs per workspace, so earlier workspaces may already have uploaded and built
Reserved or invalid name	Rejected locally (`agent.yaml` permits names the secrets API reserves)
Authorization	Project scope needs `PROJECT_OWNER` (or `ORG_ADMIN`); workspace scope needs `PROJECT_OWNER` or `AGENT_DEVELOPER`
Validation	A workspace’s `artifact_repositories` must pass schema and cross-file validation before any of its secrets are uploaded, on both the single-workspace and `--all` paths
`--all`	Uploaded per workspace; a failure fails only that workspace

Secret values never appear in stdout, logs, or error text — a failing upload is scrubbed via the same path as agentengine secret set.

Local testing

# Shared agentconfig library
go test ./client-libraries/agent-config/agentconfig/... -run 'LoadProjectFilesFromDir|ArtifactRegistry'
# CLI unit tests
go test ./client-libraries/agentengine-cli/internal/cmd/... -run 'ArtifactRegistry|RunValidate_Artifact'
# Build pre-check
go test ./client-libraries/agentengine-cli/internal/cmd/... -run 'RunBuild_InvalidArtifactRegistry'

Manual smoke test

Create a temp agent dir with agent.yaml, pyproject.toml, and optional uv.lock.
Run go run ./client-libraries/agentengine-cli/cmd/agentengine agent validate from that directory (or pass the manifest path).
Add a bad artifact_repositories entry and confirm exit 1 before any build upload.
Log in and run agentengine agent validate to see secret warnings; repeat with --strict.

Related docs

ECP build-start validation: docs/executor/artifact-registry-validation.md in the agentic-platform monorepo (operator documentation; not shipped in the client-libraries mirror)
artifact_repositories field reference and setup: client-libraries/docs/agent-yaml.md

Back

update

custom-artifact-source