CLIでのアーティファクトレジストリの検証

フラグのリファレンス: agentengine エージェント validate、agentengine ビルドする

対象読者: agentengine agent validate または agentengine build を実行している CLI ユーザー。

CLIは、ECPのビルド開始時の検証と同じdeclared-インデックスアーティファクトレジストリチェックを、アーカイブをアップロードする前にローカルで実行します。

コマンド

コマンド	厳密な検証	シークレットに関する警告
`agentengine agent validate [path]`	`artifact_repositories` が空でない場合	ログイン時（ベストエフォート）; `--strict` → exit 1
`agentengine build`	同様に、前 `InitArchiveBuild`	クライアントが利用可能な場合は常に、ノンブロッキング
`agentengine build --upload-build-secrets`	同上	環境から宣言されたシークレットを最初にアップロードします。以下を参照してください。

どちらのコマンドも、``agent.yaml`` と同じディレクトリにあるツールファイルから読み取ります。

検証される内容

常に (スキーマ — `agentconfig.Validate`)

artifact_repositories エントリの形状: name, type, secret, scope, auth, npm_scope

`artifact_repositories` が空でない場合（ファイル間）

宣言された name （または npm npm_scope）がプロジェクトツーリング内に存在する必要があります。
一致するツールエントリには、HTTPSレジストリURLが必要です。
ツールや読み込まれたロックファイル内のURLは、SSRFに対して安全でないホストがないかスキャンされます。

オプトインモデル（エラーではありません）

artifact_repositories ブロックがない場合、ファイル間のフェッチは行われません。
/ 内のプライベート HTTPS URLuv.lockpackage-lock.json で、宣言されて**いない**ものは、プラットフォームの認証情報なしで渡されます。
ツールや読み込まれたロックファイル内のSSRFに対して安全でないURLは、artifact_repositoriesが空でない場合、引き続きINVALID_REGISTRY_URLで失敗します。

シークレットの警告 (オンライン)

シークレット検索のECPスコープルールをミラーリングします。CLIでは、agentengine agent validate --strict（終了コード1）でない限り、これらは警告となります。ECP build-startは、シークレットが見つからない場合、致命的なエラー（CodeBuildの前のMISSING_BUILD_SECRET）として扱います。

コード	CLI `validate`	ECPビルドする開始	意味
`MISSING_BUILD_SECRET`	警告: `--strict` → 終了 1	ハードフェイル	宣言されたスコープにASMシークレットがありません
`SCOPE_MISMATCH_HINT`	警告: `--strict` → 終了 1	ハードフェイル	シークレットは別のスコープに存在します
`WORKSPACE_CONTEXT_NEEDED`	警告: `--strict` → 終了 1	該当なし（CLIには`agentengine init`が必要です）	ワークスペーススコープのエントリですが、ワークスペースコンテキストがありません
`SECRET_METADATA_LOOKUP_FAILED`	警告: `--strict` → 終了 1	致命的なエラー（再試行不可）。一時的なエラーの場合は再試行されます	オンラインのシークレットリストを検証できませんでした

ファイル間のハードエラー

これらは、artifact_repositories が空でない場合、agentengine agent validate、agentengine build（アップロード前）、および ECP ビルドする開始のクロスチェックに失敗します。

コード	意味	対応策
`UNKNOWN_INDEX_NAME`	ツール内に `name` (または npm `npm_scope`) が見つかりません	`agent.yaml` を `pyproject.toml` / `.npmrc` / `publishConfig.registry` に合わせる
`MISSING_REGISTRY_URL`	名前は一致しましたが、ツールにHTTPS URLがありません	`url` をインデックス/レジストリ設定に追加します
`INVALID_REGISTRY_URL`	HTTPS以外のURL、埋め込み認証情報、またはブロックされたホスト	`https://` を使用してください。トークンを URL に含めることは絶対に避けてください。

ロックファイル内の宣言されていないプライベートHTTPS URLは、プラットフォームの認証情報なしで通過します（オプトインモデル）。ツールや読み込まれたロックファイル内のSSRFに対して安全でないURLは、artifact_repositoriesが空でない場合、引き続きINVALID_REGISTRY_URLで失敗します。設定のチュートリアル、CIトークンの更新、Webhookの事前シード、およびベンダー提供のwheels/からの移行については、agent-yaml.mdを参照してください。

例

有効な宣言済みインデックス (Python)

agent.yaml:

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

pyproject.toml 一致する [[tool.uv.index]] 名と HTTPS url が含まれている必要があります。

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

不明な宣言された名前

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

宣言されていないロックファイルのURL（合格）

uv.lock にプライベートパッケージを持つエージェントで、artifact_repositories ブロックがない場合、0 は終了します。カスタマーマネージド認証のみが対象です。

厳密モード

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

ビルドする前に宣言されたシークレットをアップロードする

agentengine build --upload-build-secrets 短期間のレジストリトークン向けの**オプトイン**の便利な機能です。同じ名前の環境変数から各artifact_repositories[].secretを読み取り、ビルドが作成される前に、宣言されたスコープでPUTします。これは、agent.yaml が宣言していない環境変数を読み取ることはありません。

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)

このフラグがない場合、agentengine secret set <NAME>で認証情報を一度設定します。このフラグは、ビルドするの合間に期限が切れるトークンのために存在します。

動作	詳細
スコープ	エントリごと、`scope`（デフォルト`project`）から → プロジェクトまたはワークスペース`PUT`
順序	ビルドする作成前に実行されます。ECPは宣言されたシークレットをビルドする-start内のASM ARNに解決し、シークレットが存在しない場合はビルドするを失敗させます。
重複除外	同じスコープおよびプロジェクトで同じシークレットがアップロードされるのは1回のみです（全体を通しても同様です）。 `--all`
Missing / empty env var	そのエージェントのアップロードやビルドする前に失敗し、問題のある名前をすべて一度にリストアップします。`--all`の場合、解決はワークスペースごとに実行されるため、以前のワークスペースはすでにアップロードおよびビルドされている可能性があります。
予約済みまたは無効な名前	ローカルで拒否されました（`agent.yaml` は secrets API が予約している名前を指定しています）
承認	プロジェクトスコープには `PROJECT_OWNER` (または `ORG_ADMIN`) が必要です。ワークスペーススコープには `PROJECT_OWNER` または `AGENT_DEVELOPER` が必要です
検証	ワークスペースの `artifact_repositories` は、シングルワークスペースパスと `--all` パスの両方で、シークレットがアップロードされる前に、スキーマおよびファイル間検証に合格する必要があります。
`--all`	ワークスペースごとにアップロードされます。失敗した場合はそのワークスペースのみが失敗します

シークレットの値は、stdout、ログ、エラーテキストには表示されません。アップロードの失敗は、agentengine secret setと同じパスでスクラブされます。