CLI의 아티팩트 레지스트리 유효성 검사

플래그 참조: 에이전트engine 에이전트 validate, agentengine 빌드.

대상: agentengine agent validate 또는 agentengine build을(를) 실행하는 CLI 사용자.

CLI는 ECP 빌드 시작 유효성 검사와 동일한 declared-인덱스 아티팩트 레지스트리 검사를 로컬에서, 그리고 보관 업로드 전에 실행합니다.

명령.

명령	강력한 유효성 검사	보안 경고
`agentengine agent validate [path]`	`artifact_repositories`이(가) 비어 있지 않은 경우	로그인 시(최선); `--strict` → 종료 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 블록이 없으면 파일 간 가져오기가 없습니다.
uv.lock / package-lock.json에서 선언되지 않은 비공개 HTTPS URL → 플랫폼 자격 증명 없이 통과합니다.
도구 또는 로드된 잠금 파일의 SSRF에 안전하지 않은 URL은 artifact_repositories이(가) 비어 있지 않을 때 여전히 INVALID_REGISTRY_URL 오류가 발생합니다.

비밀 경고(온라인)

비밀 조회를 위한 ECP 범위 규칙을 미러링합니다. CLI에서 agentengine agent validate --strict이(가) 아닌 경우 이는 경고 입니다(종료 1). ECP 빌드-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 토큰 새로 고침, 웹후크 사전 시드 및 벤더링된 wheels/ 에서의 마이그레이션은 에이전트-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

선언되지 않은 lockfile URL (통과)

uv.lock에 private 패키지가 있지만 artifact_repositories 블록이 없는 에이전트는 0를 종료합니다. 고객-managed 인증만 가능합니다.

엄격 모드

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는 빌드 시작 시 선언된 비밀을 ASM ARN으로 확인하며, 하나라도 누락되면 빌드에 실패합니다.
중복 제거	동일한 범위와 프로젝트에서 동일한 비밀이 한 번 업로드되며, `--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과(와) 동일한 경로를 통해 삭제됩니다.