Protected Vercel Deployments（保護されたVercelデプロイメント）
呼び出し元の既存のVercel IDと短命のOIDCトークンを使用します。デプロイメント保護を無効にしたり、デプロイメントを公開したり、静的なバイパスシークレットを事前に要求したりしないでください。
同一プロジェクトのプレビュー
対象プロジェクトのローカル開発トークンは、デフォルトの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からトークンをキャプチャまたは復元しようとしないでください。
対象のプロジェクトとスコープを明示的に設定します。安全に推測できない場合は、ユーザーに質問してください。既存の .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 コマンドを繰り返します。
トークンを印刷したり、ソースに貼り付けたり、環境ファイルに保存したりしないでください。
その他の環境と呼び出し元
Trusted Sourcesの設定は、以下の場合に必要です：
- ローカル開発トークンが保護された本番デプロイメントに到達する必要がある場合
- 呼び出し元が別のVercelプロジェクトまたはチームに属している場合
- 対象プロジェクトの自己アクセスルールがカスタマイズされている場合
- Vercelが
TRUSTED_SOURCES_ENVIRONMENT_MISMATCHを返す場合
Trusted Sourcesルールを編集するためのサポートされたVercel CLIや公開REST APIはありません。承認された人間が、対象プロジェクトの Settings → Deployment Protection → Trusted Sources を開き、必要な呼び出し元と環境マッピングのみを追加する必要があります。ローカルトークンは development 環境を持つため、保護された本番環境へのアクセスには development から production へのマッピングが必要です。
処理を停止し、正確なルールを人間に伝えてください。ブラウザ自動化を使用してアクセス制御を変更しないでください。関連のない環境マッピングを拡大しないでください。人間がルールの保存を確認した後、認証された open を再試行してください。
人間の介入境界
同一プロジェクトの開発からプレビューへのパスは、Vercel CLIがすでに認証されていて、対象のプロジェクトとスコープがわかっている場合は、人間の介入なしで実行できる必要があります。人間が必要なのは、以下の場合のみです：
- Vercel CLIに認証されたIDがなく、既存の
VERCEL_TOKENもない場合。対話的なvc loginにはユーザーが必要です。 - インストールされているVercel CLIが
53.3.0より古く、トークン発行前にアップグレードが必要な場合 - トークン発行のために、正しい対象プロジェクトまたはスコープを安全に推測できない場合
- Trusted Sourcesルールを追加または変更する必要がある場合。ダッシュボードが唯一サポートされている管理面であり、これはアクセス制御を変更します。
- 呼び出し元プロジェクトでOIDC連携によるセキュアバックエンドアクセスが無効になっており、Settings → Security で再有効化する必要がある場合
- 静的シークレットのフォールバックを有効化またはローテーションする必要があり、そのアクセス制御変更に対してエージェントが明示的な許可を必要とする場合。承認後、エージェントはダッシュボード操作を必要とせずに
vc project protectionを使用できます。
エージェントは各ケースを診断し、必要な正確なアクションを明示し、ユーザーが完了を確認した後に続行できます。
正しいヘッダーを使用する
Vercelが発行したトークンを次のように送信します：
x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>
x-vercel-oidc-token を使用しないでください。そのヘッダーはワークロードIDをVercel Functionに運びます。デプロイメント保護を介した受信リクエストを認証するものではありません。
障害の診断
vercel.com/loginへのリダイレクト：デプロイメント保護がリクエストを受け入れませんでした。TRUSTED_SOURCES_ENVIRONMENT_MISMATCH：トークンは有効ですが、その呼び出し元環境がターゲット環境に到達できません。- 保護通過後のアプリケーション
401または403：アプリケーション自体の認証を個別にデバッグしてください。 - 意図的に存在しないルートでのアプリケーション
404：リクエストはデプロイメント保護を通過し、アプリケーションに到達しました。
静的シークレットフォールバック
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\"}"
Cookieディレクティブは再利用可能な _vercel_jwt Cookieを作成します。そのCookieを含む保存されたブラウザ状態は、資格情報として扱ってください。
行き止まりを避ける
vercel shareCLIコマンドはありません。共有可能リンクは人間向けであり、自動化のパスではありません。vercel curlはHTTPリクエストに役立ちますが、ページをレンダリングして操作することはできません。- デプロイメント保護例外はドメインを公開します。エージェントのブロックを解除するためだけに使用しないでください。
- OIDCトークン、バイパスシークレット、認証されたURL、または保存された状態を、ログ、スクリーンショット、ソースファイル、ユーザー向け出力に公開しないでください。