보호된 Vercel 배포 (Protected Vercel Deployments)
호출자의 기존 Vercel ID와 단기 OIDC 토큰을 사용하세요. 배포 보호를 비활성화하거나, 배포를 공개로 설정하거나, 정적 우회 비밀 키를 먼저 요청하지 마세요.
동일 프로젝트 프리뷰 (Same-project preview)
대상 프로젝트의 로컬 개발 토큰은 기본 Trusted Sources 자체 접근 규칙을 통해 해당 프로젝트의 보호된 프리뷰 배포에 접근할 수 있습니다. 일반적으로 Trusted Sources 구성이 필요하지 않습니다.
로컬 ID와 Vercel CLI 버전을 확인하세요:
vc whoami
vc --version
vc project token을 실행하기 전에 Vercel CLI 53.3.0 이상이 필요합니다. 버전 50.25.0부터 53.2.x까지는 토큰을 stderr에 기록하므로 명령어 치환이 아무것도 캡처하지 못하고 자격 증명이 로그에 나타날 수 있습니다. 설치된 버전이 더 오래된 경우 중단하고 사용자에게 업그레이드를 요청하세요. stderr에서 토큰을 캡처하거나 복구하려고 시도하지 마세요.
대상 프로젝트와 범위(scope)를 명시적으로 설정하세요. 안전하게 유추할 수 없는 경우 사용자에게 물어보세요. 기존 .vercel/project.json 링크가 대상에 대해 확인된 디렉토리에서는 프로젝트 이름 없이 vc project token을 사용해도 유효합니다. 단순히 OIDC 토큰을 얻기 위해 vc link를 실행하지 마세요. 현재 Vercel CLI 버전은 링크 시 개발 변수를 .env.local로 가져오기도 합니다.
이름이 있는 브라우저 세션을 생성하고, Vercel CLI로 개발 OIDC 토큰을 발급받은 후, 출력하거나 저장하지 않고 주입하세요:
export AGENT_BROWSER_SESSION="$(agent-browser session id --scope worktree --prefix vercel-preview)"
export VERCEL_PREVIEW_URL="https://my-app.vercel.app"
export VERCEL_PROJECT="my-app"
export VERCEL_SCOPE="my-team"
(
TOKEN="$(vc project token "$VERCEL_PROJECT" --scope "$VERCEL_SCOPE")"
test -n "$TOKEN"
agent-browser open "$VERCEL_PREVIEW_URL" --headers \
"{\"x-vercel-trusted-oidc-idp-token\":\"$TOKEN\"}"
)
agent-browser snapshot -i
동일한 세션에서 일반 워크플로우를 계속하세요. 헤더는 대상 오리진으로 범위가 지정되며 문서, 스크립트, 스타일, 글꼴 및 페이지 내 요청에 적용됩니다. 브라우저 세션이 닫히거나 다시 시작되면 인증된 open 명령어를 반복하세요.
토큰을 절대 출력하거나, 소스 코드에 붙여넣거나, 환경 파일에 저장하지 마세요.
기타 환경 및 호출자 (Other environments and callers)
다음과 같은 경우 Trusted Sources 구성이 필요합니다:
- 로컬 개발 토큰이 보호된 프로덕션 배포에 접근해야 하는 경우
- 호출자가 다른 Vercel 프로젝트나 팀에 속한 경우
- 대상 프로젝트의 자체 접근 규칙이 사용자 정의된 경우
- Vercel이
TRUSTED_SOURCES_ENVIRONMENT_MISMATCH를 반환하는 경우
Trusted Sources 규칙을 편집하기 위한 지원되는 Vercel CLI 또는 공개 REST API는 없습니다. 권한 있는 사람이 대상 프로젝트의 Settings → Deployment Protection → Trusted Sources를 열고 필요한 호출자 및 환경 매핑만 추가해야 합니다. 로컬 토큰은 development 환경을 가지므로, 보호된 프로덕션 접근을 위해서는 development에서 production으로의 매핑이 필요합니다.
중단하고 정확한 규칙을 사람에게 전달하세요. 브라우저 자동화를 사용하여 접근 제어를 변경하지 말고, 관련 없는 환경 매핑을 확장하지 마세요. 사람이 규칙 저장을 확인한 후 인증된 open을 다시 시도하세요.
사람 개입 경계 (Human intervention boundaries)
동일 프로젝트 개발에서 프리뷰 경로는 Vercel CLI가 이미 인증되었고 대상 프로젝트와 범위가 알려진 경우 사람의 개입 없이 실행되어야 합니다. 사람이 필요한 경우는 다음과 같습니다:
- Vercel CLI에 인증된 ID가 없고 기존
VERCEL_TOKEN도 없는 경우; 대화형vc login은 사용자가 필요합니다. - 설치된 Vercel CLI가
53.3.0보다 오래되어 토큰 발급 전에 업그레이드해야 하는 경우 - 토큰 발급을 위해 올바른 대상 프로젝트나 범위를 안전하게 유추할 수 없는 경우
- Trusted Sources 규칙을 추가하거나 변경해야 하는 경우; 대시보드가 유일하게 지원되는 관리 표면이며, 이는 접근 제어를 변경합니다.
- 호출 프로젝트에서 OIDC 연합을 통한 보안 백엔드 접근(Secure Backend Access with OIDC Federation)이 비활성화되어 Settings → Security에서 다시 활성화해야 하는 경우
- 정적 비밀 키 대체(static-secret fallback)를 활성화하거나 교체해야 하며, 에이전트가 해당 접근 제어 변경에 대한 명시적 권한이 필요한 경우. 승인 후 에이전트는 대시보드 상호작용 대신
vc project protection을 사용할 수 있습니다.
에이전트는 각 사례를 진단하고 필요한 정확한 조치를 설명한 후, 사용자가 완료를 확인하면 계속 진행할 수 있습니다.
올바른 헤더 사용 (Use the correct header)
Vercel에서 발급한 토큰을 다음과 같이 전송하세요:
x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>
x-vercel-oidc-token을 대체하지 마세요. 해당 헤더는 워크로드 ID를 Vercel Function으로 전달하지만, 배포 보호를 통한 인바운드 요청을 인증하지는 않습니다.
실패 진단 (Diagnose failures)
vercel.com/login으로 리디렉션: 배포 보호가 요청을 수락하지 않았습니다.TRUSTED_SOURCES_ENVIRONMENT_MISMATCH: 토큰은 유효하지만, 호출자 환경이 대상 환경에 도달할 수 없습니다.- 보호 통과 후 애플리케이션
401또는403: 애플리케이션 자체 인증을 별도로 디버깅하세요. - 의도적으로 누락된 경로에서 애플리케이션
404: 요청이 배포 보호를 통과하여 애플리케이션에 도달했습니다.
정적 비밀 키 대체 (Static-secret fallback)
OIDC가 불가능하거나 도구가 Trusted Sources 헤더를 보낼 수 없는 경우에만 Protection Bypass for Automation을 사용하세요. 이를 활성화하거나 교체하면 접근 제어가 변경되므로 먼저 명시적 승인을 받으세요. 독립적으로 교체할 수 있도록 전용 비밀 키를 생성하고, 환경 변수에 보관한 후 헤더로 전달하세요:
vc project protection enable <project> --protection-bypass \
--protection-bypass-secret "$VERCEL_AUTOMATION_BYPASS_SECRET"
agent-browser open "$VERCEL_PREVIEW_URL" --headers \
"{\"x-vercel-protection-bypass\":\"$VERCEL_AUTOMATION_BYPASS_SECRET\",\"x-vercel-set-bypass-cookie\":\"true\"}"
쿠키 지시문은 재사용 가능한 _vercel_jwt 쿠키를 생성합니다. 해당 쿠키가 포함된 저장된 브라우저 상태를 자격 증명으로 취급하세요.
막다른 길 피하기 (Avoid dead ends)
vercel shareCLI 명령어는 없습니다. 공유 가능 링크(Shareable Links)는 사람을 위한 것이며 자동화 경로가 아닙니다.vercel curl은 HTTP 요청에 유용하지만 페이지를 렌더링하고 상호작용할 수 없습니다.- 배포 보호 예외(Deployment Protection Exceptions)는 도메인을 공개로 만듭니다. 단순히 에이전트를 차단 해제하기 위해 사용하지 마세요.
- OIDC 토큰, 우회 비밀 키, 인증된 URL 또는 저장된 상태를 로그, 스크린샷, 소스 파일 또는 사용자에게 표시되는 출력에 노출하지 마세요.