vercel-deploy

Vercel デプロイ

汎用的なロールアウト方針の設計ではなく、Vercel 上のデプロイを具体的に運用する場合に、このスキルを使用してください。

vercel-deploy は、以下の操作を行うためのプロバイダー固有の入り口です。

• Vercel プレビューのデプロイを作成または更新する
• Vercel で本番環境に直接デプロイする
• デプロイをステージングし、検証してから本番環境に反映する
• 安定したプレビューエイリアスを割り当てる、またはカスタムドメインを設定する
• Vercel 環境変数のスコープと再デプロイの必要性を調査・修正する
• 本番環境のデプロイに問題が発生した場合、ロールバックを中心に確認する

モードを選ぶ前に、以下のサポートドキュメントを読んでください。

• references/modes-and-boundaries.md
• references/preview-production-command-packets.md
• references/env-domain-rollback-troubleshooting.md

このスキルを使う場合

• ユーザーがプロジェクトをVercel にデプロイしたいと明示している
• Vercel のプレビュー URL、プレビューエイリアス、または安定したデモ環境に関する作業である
• 既存の Vercel デプロイがリンクされており、本番反映またはロールバックへの対応が必要である
• 主な問題が Vercel の環境変数スコープ、Vercel のドメイン／エイリアスの状態、または Vercel 固有のリリース検証である
• プロバイダーがすでに選定されており、ベンダー中立のリリース設計ではなく、Vercel の運用ガイダンスが必要である

このスキルを使わない場合

• 主な質問が汎用的なロールアウト戦略、リリースゲート、カナリア方針、またはプロバイダー横断のデプロイ設計である → deployment-automation を使用してください
• 主な作業がデプロイフロー周辺の GitHub Actions／CI YAML／タスクランナーの編集である → deployment-automation を使用してください
• 主な作業が Node、Vercel CLI、認証の初期設定のインストール、またはローカルマシンのリンクである → system-environment-setup を使用してください
• デプロイ手順が機能する前に、アプリ／フレームワーク／ビルドに問題がある → まず debugging または該当するフレームワーク／ビルドのスキルを使用してください
• 主な作業がリリース後の長期的なテレメトリー、SLO、またはアラート設定である → monitoring-observability を使用してください

手順

ステップ 1：Vercel の作業内容を 1 つのパケットにまとめる

コマンドを使う前に、主要なモードを必ず 1 つ選んでください。

vercel_packet:
  primary_mode: preview-deploy | production-deploy | promote-preview | alias-domain | env-sync | rollback-response
  project_state: linked | unlinked | unknown
  build_mode: source-build | prebuilt | unknown
  target_environment: preview | production | development | custom | unknown
  url_goal: generated-url | stable-preview-alias | custom-domain | mixed | none
  verification_depth: none | smoke | health-plus-logs | release-checklist

主要なモード：

• preview-deploy — テスト可能な Vercel プレビューを作成または更新する
• production-deploy — 新しい本番環境への直接デプロイを実行する
• promote-preview — 既存のデプロイを検証してから、現行デプロイにする
• alias-domain — 安定したプレビューエイリアスまたはカスタムドメインを設定／検証する
• env-sync — 環境変数のスコープ、または古くなったローカル／プロジェクト環境の状態を修正する
• rollback-response — 本番環境を既知の正常なデプロイに戻し、復旧を検証する

依頼に複数の目標が含まれている場合は、最初の回答の中心となるものを選び、残りを明示的に振り分けてください。

ステップ 2：必要最小限の、事実に基づく証拠を集める

フレームワーク名だけから推測してはいけません。まず、信頼できる最小限の情報を確認してください。

1. プロジェクトはすでに Vercel にリンクされていますか（vercel link、.vercel/project.json、またはダッシュボード上の証拠で確認できます）？
2. 対象は本当にプレビュー、本番環境、それともカスタム／開発環境ですか？
3. デプロイ手順はソースベースですか、それともビルド済みの成果物を使いますか？
4. ユーザーが必要としているのは、生成されたデプロイ URL、安定したエイリアス、それともカスタムドメインですか？
5. これは本当にデプロイ／切り替えの問題ですか。それとも、再デプロイがまだ必要な環境変数／設定の不一致ですか？
6. どのような証明が必要ですか：URL のみ、スモークチェック、ヘルスチェックとログ、DNS 検証、またはロールバックの検証ですか？

不明な項目があれば、モードが完全に確定しているかのように装わず、前提を明示してください。

ステップ 3：該当する運用手順を使う

すべてのコマンドを一度に並べてはいけません。モードに合ったリファレンスパケットを選んでください。

A. preview-deploy

成果物がテスト可能なプレビュー環境へのデプロイである場合に使用します。

• リンク済みプロジェクトの CLI、またはダッシュボードを利用したプレビューのフローを優先します。
• 生成されたデプロイ URL と、安定したエイリアスの計画を返します。
• 目的が安定したデモ URL の場合は、すべてをひとまとめにせず、結果を alias-domain に引き継ぎます。

使用するパケット：references/preview-production-command-packets.md#preview-deploy-packet

B. production-deploy

ユーザーが今すぐ新たに本番環境へデプロイすることを明示的に希望している場合に使用します。

• ソースからビルドするのか、ビルド済みの成果物を使うのかを伝えます。
• 到達した本番 URL／ドメインを報告します。
• デプロイの成功とデプロイ後の検証を分けて報告します。

使用するパケット：references/preview-production-command-packets.md#direct-production-deploy-packet

C. promote-preview

すでにデプロイが存在し、安全に切り替えることが目的の場合に使用します。

• 昇格の前に、対象となるデプロイ URL／コミットが正確であることを確認します。
• 昇格は、魔法のようにポインターを切り替える操作ではなく、リリース操作として扱います。
• 重要な場合は、チームのスコープやドメインに関する注意事項を記載します。
• 本番環境の検証結果は、昇格コマンドとは別に報告します。

使用するパケット：references/preview-production-command-packets.md#staged-production--promote-packet

D. alias-domain

安定した URL が実際の成果物である場合に使用します。

• 生成された URL、安定したプレビューエイリアス、本番のカスタムドメインを区別します。
• DNS／手動での検証状況は、CLI の成功とは別に報告します。
• フォールバック用の証拠として、元のデプロイ URL も利用できる状態にしておきます。

使用するパケット：references/env-domain-rollback-troubleshooting.md#aliases-and-domains

E. env-sync

環境変数が不足している、古くなっている、または誤ったスコープに設定されているため、プレビュー環境と本番環境の動作が異なる場合に使用します。

• まず、対象となる環境を確認します。
• 環境変数の変更は古いデプロイではなく、新しいデプロイに適用されることを明記します。
• Vercel の環境スコープと、アプリケーションレベルで想定される正規 URL／設定を区別します。

使用するパケット：references/env-domain-rollback-troubleshooting.md#environment-variables

F. rollback-response

本番トラフィックをすばやく戻す必要がある場合に使用します。

• 現在問題のあるデプロイと、正確なロールバック先を特定します。
• 復旧したと断言する前に、古い設定、cron、プラン上限に関する注意事項を明記します。
• ロールバック後に、本番のログとヘルス状態を再確認します。

使用するパケット：references/env-domain-rollback-troubleshooting.md#rollback

Step 4: 回答時は役割の境界を明確に保つ

依頼の内容が範囲から外れた場合は、以下の振り分け表を使用します。

依頼の内容が次のような場合	使用するもの
「プロバイダー全体のリリースゲート、カナリアポリシー、またはロールバック戦略を設計する」	deployment-automation
「Vercel コマンドを実行する GitHub Actions ワークフローを書き換える」	deployment-automation
「Vercel CLI、認証、Node をインストールする、またはローカルの認証情報をリンクする」	system-environment-setup
「デプロイが成功する前にビルドがクラッシュする」	debugging またはフレームワーク固有のスキル
「ダッシュボード、アラート、またはリリース後の長期的な監視を設定する」	monitoring-observability
「Vercel 上で調査、デプロイ、昇格、エイリアス設定、ドメイン管理、環境変数の同期、またはロールバックを行う」	vercel-deploy

Step 5: レガシーの claimable デプロイヘルパーについては、環境が明示的に依存している場合に限り言及する

このディレクトリには、tarball をパッケージ化してプレビュー URL／claim URL を返す、claimable プレビュー用ヘルパー scripts/deploy.sh が引き続き含まれています。これは環境固有のレガシーなショートカットとして扱い、Vercel の標準的な運用モデルとしては扱わないでください。

次の条件をすべて満たす場合に限り使用します。

• ランタイムが claimable デプロイエンドポイントを明示的に必要としている
• 作業内容が claimable プレビュー URL の作成のみである
• リンク済みプロジェクト、昇格、エイリアス／ドメイン、環境変数の同期、ロールバックの各操作が対象外である

それ以外の場合は、上記で説明した公式の Vercel CLI／ダッシュボードモデルを優先してください。

出力形式

単独のコマンドを羅列するのではなく、モード別のパケットを返します。

最低限の構成：

# Vercel Operation Summary
- Mode:
- Project linked:
- Build mode:
- Target environment:
- URL / deployment:
- Verification performed:
- Remaining risk or manual step:
- Routed-out work (if any):

例

例 1：安定したエイリアスを使ったプレビューデプロイ

ユーザーの依頼：「この Next.js ブランチを Vercel にデプロイして、安定したプレビュー URL を教えてください。」

期待される対応：

• 主なモードとして preview-deploy を選択する
• プレビューパケットを使ってデプロイする
• 生成されたデプロイ URL を取得する
• 安定したエイリアスは別途適用するか、適用手順を提示する
• 両方の URL と、必要な DNS 設定や手動作業があればそれも伝える

例 2：検証済みのステージングデプロイを昇格する

ユーザーの依頼：「この Vercel ビルドはすでに QA に合格しています。本番環境に昇格して検証してください。」

期待される対応：

• 主なモードとして promote-preview を選択する
• まず正確なデプロイ／コミットを検証する
• ステージングから本番環境への昇格パケットを実行する
• 昇格後に本番環境で検証した結果を報告する
• 該当する場合はスコープやドメインに関する注意点を伝える

例 3：Vercel の環境変数がデプロイに反映されない

ユーザーの依頼：「Vercel には変数がありますが、デプロイから読み取れません。」

期待される対応：

• env-sync を選択する
• 意図した環境スコープを確認する
• 環境変数の変更後に新しいデプロイが行われたか確認する
• 信頼できる状態確認として Vercel の環境変数の確認／取得を使う
• アプリ側で正規の URL／設定が引き続き必要かどうかを明示する

例 4：一般的なリリース設計の依頼を振り分ける

ユーザーの依頼：「プロバイダーをまたぐ、ステージングから本番環境へのロールアウト方針とカナリアリリースのルールを設計してください。」

期待される対応：

• Vercel だけで完結する操作であるかのように扱わない
• 中心となる作業は deployment-automation に振り分ける
• 明示的に Vercel 固有の追加作業がある場合のみ、vercel-deploy に残す

ベストプラクティス

1. コマンドを提示する前に、主な Vercel モードを 1 つ選びます。
2. 従来の tarball を使った簡易手順より、リンク済みプロジェクトでの公式 CLI／ダッシュボードの手順を優先します。
3. デプロイ、昇格、エイリアス／ドメイン、環境変数の修正、ロールバックは、それぞれ別のオペレーターパケットとして扱います。
4. 生成されたデプロイ URL、安定したプレビューエイリアス、カスタムドメインを必ず区別します。
5. 環境変数の変更は新しいデプロイにのみ反映される点に注意します。
6. vercel promote やロールバックが損失なく行えると過度に期待させず、スコープ／ドメイン／プラン／設定に関する注意点を伝えます。
7. 重複を避けるため、一般的なロールアウト設計は deployment-automation に振り分けます。

参考資料

• Vercel CLI からのプロジェクトのデプロイ
• vercel deploy
• vercel promote
• vercel rollback
• 環境変数
• システム環境変数
• ドメインの操作
• Vercel による Git リポジトリのデプロイ