Deploy

Deploy

Streamline deployment workflows for React, Next.js, NestJS applications to various environments.

Contract

Inputs:

• Repository root
• Target environment: preview, staging, or production
• Optional branch, PR number, deployment provider, and health-check URL

Outputs:

• Pre-deploy gate results
• Deployment route and provider
• Verification status
• Rollback or follow-up instructions when needed

Creates/Modifies:

• Local changes only when fixing failed gates before deployment
• Release PRs only when delegated to release-pr-gates

External Side Effects:

• May trigger provider deployments
• May create or update GitHub PRs through delegated release skills
• May read logs and monitoring systems

Confirmation Required:

• Before production deploys
• Before merging release PRs
• Before rollback commands
• Before force-pushes or history rewriting

Delegates To:

• deployment-composer for route discovery across providers
• release-pr-gates for branch promotion PRs
• gh-fix-ci for failed GitHub Actions checks
• ec2-backend-deployer for EC2/Docker deployment setup

When to Use

• Deploying to staging or production
• Setting up deployment pipelines
• Managing environment-specific deployments

Local Quality Gates (MANDATORY)

Always run format, lint, and type-check locally before every release PR or deployment. These mirror the expected GitHub Actions gates and are cheap enough to run before pushing.

Use the repository's package manager and scripts when present. Prefer existing scripts in package.json; fall back only when a script is missing.

# 1. Format - required
bun run format || npm run format || npx biome check --write .

# 2. Lint - required
bun run lint || npm run lint || bunx turbo lint

# 3. Type-check - required
bun run typecheck || bun run type-check || npm run typecheck || npm run type-check || npx tsc --noEmit

# 4. Tests - run when configured
npm test || bun run test --filter=[changed-package]

# 5. Build - run when configured
npm run build

If format, lint, or type-check fails, fix it before pushing, opening a release PR, or triggering deployment. Do not hand known local quality failures to GitHub Actions.

Deployment Process

To Staging

1. Ensure trunk CI is green 2. Trigger deploy to staging environment from the trunk (no staging branch) 3. Wait for CI and staging health checks to pass

To Production

1. Ensure staging environment is healthy 2. Require explicit confirmation — production is critical 3. Deploy to production environment from the trunk 4. Monitor deployment 5. Watch health endpoints and error tracking for 15 minutes

Hotfix Flow

1. Branch hotfix/xxx off the trunk (default branch) 2. Fix -> PR to trunk -> merge -> deploy to production

Post-Deployment Verification

1. Check health endpoints 2. Monitor error tracking (Sentry, etc.) 3. Verify critical user flows 4. Check deployment logs

Rollback

If deployment fails, revert the merge commit and re-deploy.

References

See references/workflow.md for platform-specific deployment details, AWS patterns, CI/CD integration, and rollback procedures.

Deployment Workflow Reference

Detailed deployment patterns for various platforms and frameworks.

Project Context Discovery

Before deploying, discover the project's setup:

1. Identify Project Type: Scan for package.json, next.config.js, nest-cli.json, vite.config.js 2. Discover Deployment Platform: Check for AWS configs, vercel.json, Dockerfiles, .github/workflows/ 3. Identify Build Commands: Check package.json scripts for build, build:prod, build:staging 4. Check Environment Configuration: Review .env.example for required variables

Framework-Specific Deployment

Next.js (Vercel)

vercel --prod    # Production
vercel           # Preview

NestJS (Docker/AWS)

docker build -t [project-name]:[tag] .
docker push [registry]/[project-name]:[tag]

React (Static Hosting)

npm run build
aws s3 sync build/ s3://[bucket-name] --delete
aws cloudfront create-invalidation --distribution-id [id] --paths "/*"

AWS Patterns

ECS/Fargate

aws ecs update-service \
  --cluster [cluster-name] \
  --service [service-name] \
  --force-new-deployment

Lambda

serverless deploy --stage [environment]

S3/CloudFront Static

npm run build
aws s3 sync build/ s3://[bucket] --delete --cache-control "max-age=31536000"
aws cloudfront create-invalidation --distribution-id [id] --paths "/*"

Database Considerations

Before deployment:

1. Run migrations: npm run migrate:up or equivalent 2. Verify connection strings for target environment 3. Check replica set configuration and network access 4. Verify indexes are created

Rollback Procedures

Docker/ECS

aws ecs update-service \
  --cluster [cluster] \
  --service [service] \
  --task-definition [previous-version]

Vercel

vercel rollback

Database

npm run migrate:down

Deployment Patterns

• Blue-Green: Deploy new version alongside old, switch traffic when verified
• Canary: Deploy to small percentage, gradually increase if healthy
• Rolling: Update instances one at a time, maintain availability

CI/CD Integration

# Check GitHub Actions
ls .github/workflows/

# Trigger deployment workflow
gh workflow run deploy.yml --ref main -f environment=production

Safety Features

Always include for production:

• [ ] All tests passing
• [ ] Build successful
• [ ] Environment variables configured
• [ ] Database migrations ready
• [ ] Rollback plan prepared
• [ ] Team notified