vercel__vercel-plugin/commands/deploy.md.tmpl

---
description: Deploy the current project to Vercel. Pass "prod" or "production" as argument to deploy to production. Default is preview deployment.
---

# Deploy to Vercel

Deploy the current project to Vercel using the CLI, with preflight safety checks, explicit production confirmation, and post-deploy verification.

## Preflight

Run these checks before any deployment. Stop on failure and print actionable guidance.

1. **CLI available?** — Confirm `vercel` is on PATH.
   - If missing: `npm i -g vercel` (or `pnpm add -g vercel` / `bun add -g vercel`).
2. **Project linked?** — Check for `.vercel/project.json` in the current directory or nearest parent.
   - If not found: run `vercel link` interactively, then re-run `/deploy`.
3. **Monorepo detection** — Look for `turbo.json` or `pnpm-workspace.yaml` at the repo root.
   - If detected: confirm which package is targeted. If ambiguous, ask the user before proceeding.
4. **Uncommitted changes** — Run `git status --porcelain`.
   - If output is non-empty: warn the user that uncommitted changes will **not** be included in the deploy. Ask whether to continue or commit first.
   - If not a git repo, skip this check.
5. **Observability preflight** (production deploys only) —

Before promoting to production, verify observability readiness:

- **Drains check**: Query configured drains via MCP `list_drains` or REST API. If no drains are configured on a Pro/Enterprise plan, warn:
  > ⚠️ No drains configured. Production errors won't be forwarded to external monitoring.
  > Configure drains via Dashboard or REST API before promoting.
- **Errored drains**: If any drain is in error state, warn and suggest remediation before deploying:
  > ⚠️ Drain "<url>" is errored. Fix or recreate before production deploy to avoid monitoring gaps.
- **Error monitoring**: Check that at least one of these is in place: configured drains, an error tracking integration (e.g., Sentry, Datadog via `vercel integration ls`), or `@vercel/analytics` in the project.
- These are warnings, not blockers — the user may proceed after acknowledgment.

## Plan

State the intended action before executing:

- **Preview deploy** (default): `vercel` — creates a preview deployment on a unique URL.
- **Production deploy**: `vercel --prod` — deploys to production domains.

If "$ARGUMENTS" contains "prod" or "production":

> ⚠️ **Production deployment requested.**
> This will deploy to your live production URL and affect real users.
> **Ask the user for explicit confirmation before proceeding.** Do not deploy to production without a clear "yes."

If "$ARGUMENTS" does not indicate production:

> Deploying a **preview** build. This creates an isolated URL and does not affect production.

## Commands

### Preview Deployment

<!-- Sourced from deployments-cicd skill: Deployment Commands > Preview Deployment -->
{{include:skill:deployments-cicd:Deployment Commands > Preview Deployment}}

### Production Deployment (requires confirmation)

<!-- Sourced from deployments-cicd skill: Deployment Commands > Production Deployment -->
{{include:skill:deployments-cicd:Deployment Commands > Production Deployment}}

Capture the full command output. Extract the **deployment URL** from the output (the line containing the `.vercel.app` URL or custom domain URL).

Record the current git commit SHA for the summary:

```bash
git rev-parse --short HEAD
```

## Verification

After deployment completes, verify the result:

### 1. Inspect the Deployment

<!-- Sourced from deployments-cicd skill: Deployment Commands > Inspect Deployments -->
{{include:skill:deployments-cicd:Deployment Commands > Inspect Deployments}}

Extract: deployment state (READY / ERROR / QUEUED / BUILDING), build duration, framework, Node.js version, function count.

### 2. On Failure — Fetch Build Logs

If the deployment state is **ERROR** or the deploy command exited non-zero:

```bash
vercel logs <deployment-url>
```

Present the last 50 lines of build logs to help diagnose the failure. Highlight any lines containing `error`, `Error`, `ERR!`, or `FATAL`.

### 3. On Success — Quick Smoke Check

If the deployment state is **READY**, note the URL is live and accessible.

### 4. Post-Deploy Error Scan (production deploys)

For production deployments, wait 60 seconds after READY state, then scan for early runtime errors:

```bash
vercel logs <deployment-url> --level error --since 1h
```

Or via MCP if available: use `get_runtime_logs` with level filter `error`.

**Interpret results:**

| Finding | Action |
|---------|--------|
| No errors | ✓ Clean deploy — no runtime errors in first hour |
| Errors detected | List error count and first 5 unique error messages. Suggest: check drain payloads for correlated traces, review function logs in Dashboard |
| 500 status codes in logs | Correlate timestamps with drain data (if configured) or `vercel logs <url> --json` for structured output. Flag for immediate investigation |
| Timeout errors | Check function duration limits in `vercel.json` or project settings. Consider increasing `maxDuration` |

**Fallback (no drains):**

If no drains are configured, the error scan relies on CLI and Dashboard:

```bash
# Stream live errors
vercel logs <deployment-url> --level error --follow

# JSON output for parsing
vercel logs <deployment-url> --level error --since 1h --json
```

> For richer post-deploy monitoring, configure drains to forward logs/traces to an external platform via Dashboard or REST API.

## Summary

<!-- Sourced from deployments-cicd skill: Deploy Summary Format -->
{{include:skill:deployments-cicd:Deploy Summary Format}}

## Next Steps

<!-- Sourced from deployments-cicd skill: Deploy Next Steps -->
{{include:skill:deployments-cicd:Deploy Next Steps}}