Vercel Deploy

Vercel Deploy

Use this skill when the job is operating a deployment on Vercel specifically, not designing generic rollout policy.

vercel-deploy is the provider-specific front door for:

• creating or refreshing Vercel preview deployments
• running a direct production deployment on Vercel
• staging a deploy, verifying it, then promoting it live
• assigning a stable preview alias or attaching a custom domain
• inspecting/fixing Vercel environment-variable scope and redeploy needs
• responding to a bad production deployment with rollback-oriented checks

Read these support docs before choosing the mode:

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

When to use this skill

• The user explicitly wants to deploy a project on Vercel
• The job is about a Vercel preview URL, preview alias, or stable demo environment
• A linked Vercel deployment already exists and needs promotion or rollback handling
• The main issue is Vercel env scope, Vercel domain/alias state, or Vercel-specific release verification
• The provider has already been chosen and the user needs Vercel operator guidance rather than vendor-neutral release design

When not to use this skill

• The main question is generic rollout strategy, release gating, canary policy, or cross-provider deployment design → use deployment-automation
• The main job is editing GitHub Actions / CI YAML / task runners around the deploy flow → use workflow-automation
• The main job is installing Node, Vercel CLI, auth bootstrap, or linking the local machine → use system-environment-setup
• The app/framework/build is broken before the deploy path itself works → use debugging or the relevant framework/build skill first
• The main job is long-lived telemetry, SLOs, or alerting after release → use monitoring-observability

Instructions

Step 1: Normalize the Vercel job into one packet

Choose exactly one primary mode before reaching for commands.

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

Primary modes:

• preview-deploy — create or refresh a testable Vercel preview
• production-deploy — run a direct fresh production deployment
• promote-preview — verify an existing deployment, then make it current
• alias-domain — apply/verify a stable preview alias or custom domain
• env-sync — fix environment-variable scope or stale local/project env state
• rollback-response — move production back to a known-good deployment and verify recovery

If the request contains multiple goals, pick the one that owns the first answer and route the rest explicitly.

Step 2: Gather only the minimum truthful evidence

Do not guess from the framework name alone. Confirm the smallest credible set first: 1. Is the project already linked to Vercel (vercel link, .vercel/project.json, or dashboard evidence)? 2. Is the target really preview, production, or a custom/development environment? 3. Is the deploy path source-based or prebuilt? 4. Does the user care about the generated deployment URL, a stable alias, or a custom domain? 5. Is this actually a deploy/cutover problem, or an env/config mismatch that still needs redeploy? 6. What proof is expected: URL only, smoke check, health + logs, DNS verification, or rollback verification?

If one item is unknown, state the assumption instead of pretending the mode is fully known.

Step 3: Use the matching operator path

Do not dump every command at once. Pick the reference packet that matches the mode.

A. preview-deploy

Use when the deliverable is a testable preview deployment.

• Prefer linked-project CLI or dashboard-backed preview flows.
• Return the generated deployment URL plus any stable alias plan.
• If the goal is a stable demo URL, carry the result into alias-domain rather than mixing everything into one blob.

Use packet: references/preview-production-command-packets.md#preview-deploy-packet

B. production-deploy

Use when the user explicitly wants a fresh production deployment now.

• Say whether the deployment is source-build or prebuilt.
• Report the production URL/domain reached.
• Separate deploy success from post-deploy verification.

Use packet: references/preview-production-command-packets.md#direct-production-deploy-packet

C. promote-preview

Use when a deployment already exists and the job is to cut over safely.

• Verify the exact deployment URL/commit before promotion.
• Treat promotion as a release operation, not a magical pointer flip.
• Note team-scope or domain caveats when they matter.
• Report production verification separately from the promote command itself.

Use packet: references/preview-production-command-packets.md#staged-production--promote-packet

D. alias-domain

Use when the stable URL is the real deliverable.

• Distinguish generated URL vs stable preview alias vs production custom domain.
• Report DNS/manual verification status separately from CLI success.
• Keep the raw deployment URL available as fallback evidence.

Use packet: references/env-domain-rollback-troubleshooting.md#aliases-and-domains

E. env-sync

Use when preview/prod behavior differs because variables are missing, stale, or scoped incorrectly.

• Check the intended environment first.
• Call out that env-var changes apply to new deployments, not old ones.
• Distinguish Vercel env scope from app-level canonical URL/config expectations.

Use packet: references/env-domain-rollback-troubleshooting.md#environment-variables

F. rollback-response

Use when production traffic must revert quickly.

• Identify the currently bad deployment and the exact rollback target.
• Call out stale-config / cron / plan-limit caveats before claiming recovery.
• Re-check production logs/health after rollback.

Use packet: references/env-domain-rollback-troubleshooting.md#rollback

Step 4: Keep boundaries clean while answering

Use this route-out table whenever the request drifts.

Step 5: Mention the legacy claimable deploy helper only if the environment explicitly depends on it

This directory still ships scripts/deploy.sh, a claimable-preview helper that packages a tarball and returns preview/claim URLs. Treat it as a legacy environment-specific shortcut, not the default Vercel operating model.

Use it only when all of these are true:

• the runtime explicitly expects the claimable deploy endpoint
• the job is just creating a claimable preview URL
• linked-project, promotion, alias/domain, env-sync, and rollback operations are out of scope

Otherwise prefer the official Vercel CLI / dashboard model described above.

Output format

Return a mode-specific packet instead of a loose command dump.

Minimum structure:

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

Examples

Example 1: Preview deploy with stable alias

User asks: “Deploy this Next.js branch to Vercel and give me a stable preview URL.”

Expected move:

• choose preview-deploy as the primary mode
• deploy via the preview packet
• capture the generated deployment URL
• apply or plan a stable alias separately
• return both URLs and any DNS/manual step still needed

Example 2: Promote a verified staged deployment

User asks: “This Vercel build already passed QA. Promote it to production and verify it.”

Expected move:

• choose promote-preview as the primary mode
• verify the exact deployment/commit first
• run the staged-production promote packet
• report production verification after promotion
• mention scope/domain caveats if they apply

Example 3: Vercel env vars not showing up in deploys

User asks: “The variable is in Vercel, but the deployment can’t read it.”

Expected move:

• choose env-sync
• verify the intended environment scope
• confirm whether a new deployment happened after the env change
• use Vercel env inspection/pull as the trusted state check
• call out any app-level canonical URL/config still required

Example 4: Route out generic release design

User asks: “Help me design our staging-to-prod rollout policy and canary rules across providers.”

Expected move:

• do not pretend this is a Vercel-only operation
• route the main job to deployment-automation
• keep only any explicitly Vercel-specific follow-up inside vercel-deploy

Best practices

1. Pick one primary Vercel mode before giving commands. 2. Prefer linked-project, official CLI/dashboard flows over legacy tarball shortcuts. 3. Treat deploy, promote, alias/domain, env repair, and rollback as distinct operator packets. 4. Always distinguish generated deployment URLs, stable preview aliases, and custom domains. 5. Remember that env-var changes only affect new deployments. 6. Do not oversell vercel promote or rollback as lossless; call out scope/domain/plan/config caveats. 7. Route generic rollout design back to deployment-automation to avoid overlap.

References

• Deploying Projects from Vercel CLI
• vercel deploy
• vercel promote
• vercel rollback
• Environment variables
• System environment variables
• Working with domains
• Deploying Git Repositories with Vercel

Vercel Env / Domain / Rollback Troubleshooting

Environment variables

Reliable facts to preserve

• Environment-variable changes apply to new deployments, not previous ones.
• Variables can be scoped to production, preview, development, or custom environments.
• System vars like VERCEL_ENV, VERCEL_TARGET_ENV, and VERCEL_URL help, but app-specific canonical URLs may still need explicit configuration.

Troubleshooting checklist

1. Confirm which environment the variable should target. 2. Confirm a new deployment happened after the variable changed. 3. Use vercel env ls or environment-specific settings as the trusted state check if the UI seems inconsistent. 4. Check whether the app expects a canonical callback/base URL instead of only VERCEL_URL. 5. Report whether the issue is Vercel env scope, app config, or both.

Aliases and domains

Common distinctions

• Generated deployment URL: unique *.vercel.app deployment address
• Stable preview alias: team-defined URL pointed at the latest preview deployment
• Custom domain: production-facing or long-lived host name requiring domain ownership / DNS correctness

Troubleshooting checklist

1. Confirm whether the target is preview-only or production-facing. 2. Confirm whether the alias/domain should move with each deployment or stay on production only. 3. Report DNS/manual verification steps separately from Vercel CLI success. 4. If alias errors appear, keep the deployment URL available as fallback evidence.

Rollback

Caveats from Vercel docs

• rollback restores a previous deployment state; it is not a magical patch of the current one
• environment/config may be stale relative to current project settings
• cron-job state can revert with the rolled-back deployment
• rollback eligibility differs by plan

Rollback checklist

1. Identify the currently bad production deployment. 2. Identify the target rollback deployment. 3. State stale-config caveats before calling rollback complete. 4. Re-check logs/health on production after rollback. 5. Record any follow-up needed (reapply env changes, re-run migrations, review cron config, etc.).

Vercel Deploy Modes and Boundaries

Primary modes

1. preview-deploy

Use when the main deliverable is a testable preview deployment URL on Vercel.

Signals:

• "Deploy this branch"
• "Give me a preview URL"
• "Create a PR/demo deployment"

Typical commands:

• vercel link
• vercel pull --yes --environment=preview
• vercel deploy
• vercel deploy --prebuilt
• vercel inspect <deployment-url>

2. production-deploy

Use when the user explicitly wants a fresh production deployment on Vercel.

Signals:

• "Deploy this to Vercel production"
• "Ship this live on Vercel now"

Typical commands:

• vercel pull --yes --environment=production
• vercel deploy --prod
• vercel build --prod && vercel deploy --prebuilt --prod

3. promote-preview

Use when a preview deployment already exists and the job is to promote that exact deployment after verification.

Signals:

• "Promote this preview to production"
• "This preview is good — make it prod"

Typical commands:

• vercel list --environment preview
• vercel inspect <deployment-url>
• vercel curl /api/health --deployment <deployment-url>
• vercel logs --deployment <deployment-url> --level error --limit 50
• vercel promote <deployment-url> --yes

4. alias-domain

Use when the stable URL is the actual goal.

Signals:

• "Give this preview a stable URL"
• "Attach this custom domain"
• "Alias the deployment"

Typical commands:

• vercel alias set <deployment-url> <alias>
• domain/dashboard verification steps

5. env-sync

Use when the deployment behavior differs because variables are missing, stale, or scoped to the wrong environment.

Signals:

• "The variable is in Vercel but not in the deployment"
• "Preview has the wrong config"
• "Production picked up the wrong env"

Typical commands:

• vercel env ls
• vercel pull --yes --environment=preview
• vercel pull --yes --environment=production

6. rollback-response

Use when a bad production deployment must revert quickly.

Signals:

• "Roll back the broken deploy"
• "Restore the previous production build"

Typical inputs:

• current broken deployment
• target rollback deployment
• env/config caveats
• post-rollback verification plan

Boundary rules

Legacy helper note

The bundled scripts/deploy.sh is a legacy claimable-preview helper. Treat it as an environment-specific shortcut, not the default Vercel operating model.

Preview / Production Command Packets

Use these packets as starting points. Adjust only after checking linked-project state, target environment, and verification depth.

Preview deploy packet

# Link once per repo if needed
vercel link

# Pull preview config/env metadata when using CLI-based builds
vercel pull --yes --environment=preview

# Source-based preview deploy
vercel deploy

# Or prebuilt preview deploy
vercel build
vercel deploy --prebuilt

# Inspect and verify
vercel inspect <deployment-url>
vercel logs --deployment <deployment-url> --level error --limit 50

Preview packet reminders:

• Capture the deployment URL from stdout and report it back.
• If the user needs a stable URL, continue into alias/domain handling instead of hiding it inside the deploy step.

Stable preview alias packet

url="$(vercel deploy --prebuilt)"
vercel alias set "$url" preview.example.com

Alias reminders:

• Keep the raw deployment URL in the report as fallback evidence.
• Say whether the alias is preview-only or intended to become production-facing later.

Staged production + promote packet

# Prepare production config without switching traffic yet
vercel pull --yes --environment=production
vercel build --prod
url="$(vercel deploy --prebuilt --prod --skip-domain)"

# Verify the staged deployment before cutover
vercel inspect "$url"
vercel logs --deployment "$url" --level error --limit 50
vercel curl /api/health --deployment "$url"

# Promote after verification
vercel promote "$url" --yes
vercel promote status
vercel logs --environment production --level error --since 5m

Promotion reminders:

• Verify the exact deployment URL/commit before promoting.
• In team-scoped setups, be ready to add --scope <team> if promotion auth/team context is ambiguous.
• Treat post-promote health/log checks as a separate required step.

Direct production deploy packet

vercel pull --yes --environment=production
vercel deploy --prod

# or, for prebuilt flows
vercel build --prod
vercel deploy --prebuilt --prod

Production packet reminders:

• State whether the deploy was source-build or prebuilt.
• Report the production URL/domain reached, not just command success.

Packet review questions

Before finalizing a response, answer: 1. Did I clearly say whether this was preview, direct production, or staged promote? 2. Did I verify the exact deployment before promoting or aliasing it? 3. Did I report the resulting URL/domain instead of only listing commands? 4. Did I call out any team-scope, DNS, or manual verification caveat that still remains? 5. Did I route generic release-policy work to deployment-automation if it appeared?