claudekit/website/src/content/docs/commands/deploy.md

title, description

title	description
/deploy	Deploy your application to staging or production with comprehensive safety checks

/deploy

Safe, automated deployments with built-in validation, health checks, and rollback capabilities.

Purpose

Handles deployment workflow including:

• Pre-deployment validation
• Build verification
• Security scanning
• Environment-specific deployment
• Post-deployment health checks
• Monitoring and rollback

Ensures safe deployments with comprehensive checks at every stage.

Usage

/deploy [environment]

Arguments

Argument	Description
staging	Deploy to staging environment
production	Deploy to production (requires confirmation)
preview	Deploy to preview/ephemeral environment

Workflow

Pre-Deploy Checks

Before any deployment, the command validates:

1. Build Verification

Python projects:

python -m build
python -m pytest

Node.js projects:

pnpm build
pnpm test

Validation:

• Build completes successfully
• No build warnings
• Build artifacts are generated
• Output size is reasonable

2. Run Tests

Executes full test suite:

# Python
pytest -v --cov=src --cov-report=term

# Node.js
pnpm test
pnpm test:e2e

Requirements:

• All tests pass
• Coverage meets threshold (80%+)
• No skipped tests
• E2E tests pass

3. Security Scan

Checks for vulnerabilities:

Node.js:

npm audit --audit-level=high
pnpm audit --audit-level=high

Python:

pip-audit
safety check

Validation:

• No high/critical vulnerabilities
• Dependencies are up to date
• No known security issues

4. Environment Verification

Staging:

• Staging branch is up to date
• No merge conflicts
• Environment variables configured

Production:

• Production branch matches main/master
• All PRs merged and approved
• Release notes prepared
• Rollback plan ready

Deploy Process

Staging Deployment

Automated deployment to staging:

# Build for staging
pnpm build:staging

# Deploy to staging environment
# (Implementation depends on your hosting)

Common platforms:

Vercel:

vercel deploy --prod=false

Cloudflare Pages:

wrangler pages deploy dist --project-name=app-staging

AWS:

aws deploy create-deployment \
  --application-name my-app \
  --deployment-group-name staging

Heroku:

git push heroku-staging main

Production Deployment

Requires explicit confirmation:

⚠️  Production Deployment
This will deploy to production environment.

Environment: production
Version: v1.2.3
Commits: 15 new commits since last deploy

Continue? (yes/no):

After confirmation:

# Tag release
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3

# Build for production
pnpm build:production

# Deploy
# (Platform-specific deployment)

Post-Deploy Validation

After deployment, automated checks run:

1. Health Checks

# Check application health
curl https://app.example.com/health

# Expected response:
{
  "status": "healthy",
  "version": "v1.2.3",
  "timestamp": "2024-01-15T10:30:00Z"
}

2. Smoke Tests

Essential functionality tests:

• Homepage loads
• API endpoints respond
• Authentication works
• Database connection active
• Critical features functional

3. Monitor Logs

Watch for errors:

# Check recent logs
# (Platform-specific log viewing)

# Look for:
# - Error patterns
# - Performance issues
# - Unexpected warnings

Examples

Deploy to Staging

/deploy staging

Output:

## Deployment Started

**Environment**: staging
**Version**: main@abc1234
**Time**: 2024-01-15 10:30:00 UTC

### Pre-Deploy Checks
- [x] Build successful
- [x] Tests passing (127 tests)
- [x] Security scan clean
- [x] Environment variables verified

### Deploying...
- [x] Build artifacts created
- [x] Uploading to staging
- [x] Deployment complete

### Post-Deploy Checks
- [x] Health check passed
- [x] Smoke tests passed
- [x] No errors in logs

## Deployment Complete

**URL**: https://staging.example.com
**Status**: Healthy
**Response Time**: 234ms

### Next Steps
1. Test the staging deployment
2. Verify all features work
3. Deploy to production when ready

Deploy to Production

/deploy production

Interactive confirmation:

⚠️  Production Deployment

**Environment**: production
**Version**: v1.2.3
**Branch**: main

### Changes Since Last Deploy
- feat(auth): add OAuth2 support (#123)
- fix(api): handle null users (#124)
- perf(db): optimize queries (#125)

**15 commits** | **5 PRs** | **3 contributors**

### Pre-Deploy Checklist
- [x] All tests passing
- [x] Security scan clean
- [x] Changelog updated
- [x] Team notified

Continue with production deployment? (yes/no): yes

After confirmation:

## Deployment Started

**Environment**: production
**Version**: v1.2.3
**Time**: 2024-01-15 14:30:00 UTC

### Pre-Deploy Checks
- [x] Build successful
- [x] Tests passing (127 tests)
- [x] Security scan clean
- [x] Release tagged

### Deploying...
- [x] Build artifacts created
- [x] Uploading to production
- [x] Deployment complete
- [x] Cache invalidated

### Post-Deploy Checks
- [x] Health check passed
- [x] Smoke tests passed
- [x] Performance metrics normal
- [x] No errors in logs

## Deployment Complete

**URL**: https://example.com
**Version**: v1.2.3
**Status**: Healthy
**Response Time**: 189ms

### Monitoring
- [ ] Watch error rates (5 min)
- [ ] Monitor performance (15 min)
- [ ] Check user feedback

### Rollback Plan
If issues occur:
```bash
/deploy rollback v1.2.2

### Deploy to Preview

For preview deployments (PR previews):

```bash
/deploy preview

Creates ephemeral environment for testing:

## Preview Deployment

**Environment**: preview-pr-123
**Branch**: feature/new-ui
**URL**: https://preview-pr-123.example.com

### Status
- [x] Deployed successfully
- [x] Ready for testing

**Expires**: 7 days

Output

Standard deployment output includes:

## Deployment Complete

**Environment**: staging
**Version**: v1.2.3
**URL**: https://staging.example.com

### Checks
- [x] Build successful
- [x] Tests passing
- [x] Security scan clean
- [x] Health check passed

### Metrics
- **Build Time**: 2m 34s
- **Deploy Time**: 1m 12s
- **Total Time**: 3m 46s
- **Response Time**: 234ms

### Next Steps
1. Test deployment
2. Monitor logs
3. Verify functionality

Rollback

If deployment issues occur:

/deploy rollback [version]

Example:

/deploy rollback v1.2.2

Reverts to previous version with zero-downtime.

Flags

Flag	Description	Example
--skip-tests	Skip test execution	/deploy staging --skip-tests
--force	Skip confirmations (dangerous!)	/deploy production --force
--dry-run	Simulate deployment	/deploy production --dry-run
--tag=[version]	Specify release tag	/deploy production --tag=v1.3.0

Environment Configuration

Configure deployment settings in CLAUDE.md:

## Deployment

### Staging
- **URL**: https://staging.example.com
- **Platform**: Vercel
- **Branch**: main
- **Auto-deploy**: Yes

### Production
- **URL**: https://example.com
- **Platform**: Vercel
- **Branch**: main
- **Auto-deploy**: No (manual approval)
- **Confirmation**: Required

### Checks
- Required: tests, security scan, build
- Optional: performance benchmarks

Related Commands

• /ship - Commit and create PR
• /test - Run tests
• /changelog - Generate release notes

Tips

Test on staging first: Always deploy to staging before production.

Use dry-run: Preview what will happen with --dry-run flag.

Monitor after deploy: Watch logs and metrics for at least 15 minutes after production deploys.

Have a rollback plan: Know how to quickly revert if issues occur.

Automate staging: Let staging deploy automatically, but keep production manual.

Tag releases: Use semantic versioning for production releases.

Update changelog: Keep changelog current with each production deployment.

Notify team: Alert team before production deployments.