gmacko-release-deploy-web

name	gmacko-release-deploy-web
description	Use when (1) deploying web application to Vercel staging or production, (2) monitoring deployment progress, (3) running post-deployment verification. Manages Vercel deployment workflow with safety checks.
license	MIT
compatibility	opencode
metadata	{"phase":"release","tier":"workhorse","permission":"ask"}

Gmacko Web Deployment (Vercel)

Deploy the Next.js web application to Vercel with proper verification and rollback planning.

When to Use

• Release preparation is complete
• Ready to deploy to staging or production
• Need to verify a deployment
• Need to rollback a deployment

Prerequisites

• Release summary exists: docs/ai/releases/[date]-v[version].md
• Vercel CLI authenticated: vercel whoami
• Vercel project linked: vercel link

Workflow

digraph deploy_web {
    rankdir=TB;
    node [shape=box];
    
    start [label="Start Deployment" shape=ellipse];
    confirm_env [label="1. Confirm Environment"];
    pre_checks [label="2. Pre-Deployment Checks"];
    ready [label="Ready?" shape=diamond];
    deploy [label="3. Execute Deployment"];
    monitor [label="4. Monitor Progress"];
    success [label="Success?" shape=diamond];
    verify [label="5. Post-Deploy Verification"];
    healthy [label="Healthy?" shape=diamond];
    document [label="6. Document Deployment"];
    rollback [label="Rollback"];
    done [label="Deployment Complete" shape=ellipse];
    failed [label="Deployment Failed" shape=ellipse];
    
    start -> confirm_env -> pre_checks -> ready;
    ready -> deploy [label="yes"];
    ready -> failed [label="no"];
    deploy -> monitor -> success;
    success -> verify [label="yes"];
    success -> rollback [label="no"];
    verify -> healthy;
    healthy -> document [label="yes"];
    healthy -> rollback [label="no"];
    rollback -> failed;
    document -> done;
}

Execution Steps

Step 1: Confirm Environment

CRITICAL: Always confirm target environment before deployment.

Ask user:

I'm preparing to deploy to Vercel.

Target Environment: [staging/production] Branch: [current branch] Version: [version from release summary]

Please confirm:

1. Is this the correct environment? (yes/no)
2. Have you reviewed the release summary? (yes/no)
3. Is this a good time to deploy? (yes/no)

For production deployments, require explicit confirmation:

⚠️ PRODUCTION DEPLOYMENT

This will affect live users. Please type "deploy to production" to confirm.

Step 2: Pre-Deployment Checks

Run verification before deploying:

# Check current deployment status
vercel ls --limit 5

# Verify build succeeds locally
pnpm build

# Check for uncommitted changes
git status

# Verify we're on the right branch
git branch --show-current

# Check Vercel project is linked
vercel project ls

Checklist:

## Pre-Deployment Checklist

- [ ] Build passes locally
- [ ] No uncommitted changes
- [ ] On correct branch
- [ ] Vercel project linked
- [ ] Environment variables verified
- [ ] Database migrations applied (if any)

Step 3: Execute Deployment

For Staging:

# Deploy to preview (staging)
vercel

# Or deploy specific branch
vercel --target preview

For Production:

# Deploy to production
vercel --prod

# With specific scope
vercel --prod --scope gmacko

Capture deployment URL:

DEPLOYMENT_URL=$(vercel --prod 2>&1 | grep -o 'https://[^ ]*')
echo "Deployment URL: $DEPLOYMENT_URL"

Step 4: Monitor Progress

Monitor deployment status:

# List recent deployments
vercel ls --limit 3

# Get deployment status
vercel inspect [deployment-url]

# Watch build logs (if available)
vercel logs [deployment-url] --follow

Report progress:

Deployment Status
=================
URL: https://my-app-abc123.vercel.app
Status: BUILDING / READY / ERROR
Build Duration: Xs

Build Logs:
[Show relevant log excerpts]

Step 5: Post-Deployment Verification

Run smoke tests on deployed environment:

## Smoke Test Checklist

### Critical Paths
- [ ] Homepage loads (< 3s)
- [ ] Sign in works
- [ ] Sign up works
- [ ] Dashboard loads (authenticated)
- [ ] Core feature works

### API Health
- [ ] tRPC endpoints responding
- [ ] Database queries working
- [ ] Auth middleware functioning

### Integrations
- [ ] Clerk authentication
- [ ] Stripe payments (test mode)
- [ ] PostHog tracking
- [ ] Sentry error reporting

Check for errors:

# Check Sentry for new errors
# (Manual: Visit Sentry dashboard)

# Check Vercel logs for errors
vercel logs [deployment-url] --since 5m

Step 6: Document Deployment

Update release summary:

## Deployment Record

### Web (Vercel)
- **Deployed at**: [timestamp]
- **Deployment URL**: [url]
- **Deployment ID**: [id]
- **Status**: SUCCESS / FAILED
- **Build time**: [Xs]

### Verification
- Smoke tests: PASSED / FAILED
- Error rate: Normal / Elevated
- Performance: Normal / Degraded

### Notes
[Any observations or issues]

Report to user:

DEPLOYMENT COMPLETE
===================

Environment: Production
URL: https://app.example.com
Deployment ID: dpl_xxxxx

Smoke Tests: 5/5 PASSED
Error Rate: Normal
Response Time: ~200ms avg

Deployment successful! Monitoring for issues...

Rollback Procedure

If issues detected:

# List previous deployments
vercel ls --limit 10

# Rollback to previous deployment
vercel rollback

# Or rollback to specific deployment
vercel rollback [deployment-url-or-id]

Document rollback:

## Rollback Record

- **Rolled back at**: [timestamp]
- **Reason**: [description]
- **Rolled back to**: [deployment-id]
- **Status**: SUCCESS

### Post-Rollback Verification
- [ ] Previous version accessible
- [ ] Core functionality working
- [ ] No data loss

Environment-Specific Notes

Staging

• Deployed from feature branches or staging branch
• Used for QA and demos
• Can have test data

Production

• Deployed from main branch only
• Affects real users
• Requires extra confirmation
• Consider deployment timing (avoid peak hours)

Error Handling

Build Failure

1. Check build logs: vercel logs [url]
2. Common causes:
   • Type errors (run pnpm typecheck)
   • Missing dependencies
   • Environment variable issues
3. Fix locally, push, redeploy

Runtime Errors

1. Check Sentry dashboard
2. Check Vercel function logs
3. Rollback if critical
4. Fix and redeploy

Performance Issues

1. Check Vercel Analytics
2. Compare with baseline
3. Identify slow endpoints/pages
4. Consider rollback if severe

Red Flags

Rationalization	Correction
"Just push to main, it'll be fine"	Follow full deployment process
"Skip smoke tests, build passed"	ALWAYS verify deployed functionality
"Production during peak hours is fine"	Deploy during low-traffic periods when possible
"Skip confirmation for staging"	Confirm environment for ALL deployments
"Rollback isn't necessary"	Always have rollback plan ready

Integration

• Input: Target environment, version
• References: Release summary, deployment history
• Output: Updated release record, deployment URL
• Next: gmacko-release-close or monitor