Deploy

Ship code to a target environment (staging, production, or custom).

Purpose

Deploy handles the release process:

• Build application artifacts
• Run pre-deployment checks
• Deploy to target environment
• Verify deployment success
• Handle rollback if needed

Input

Expect from orchestrator or user:

• Target environment (staging, production, custom)
• Version/tag to deploy (or "latest")
• Deployment configuration
• Rollback preferences

Process

1. Pre-deployment checks

Verify readiness before deploying:

pre_checks:
  - check: "All tests passing"
    command: "npm test"
    required: true

  - check: "Build succeeds"
    command: "npm run build"
    required: true

  - check: "No pending migrations"
    command: "npm run db:status"
    required: false

  - check: "Environment variables set"
    command: "scripts/check-env.sh"
    required: true

2. Build artifacts

Create deployable artifacts:

# Build application
npm run build

# Create Docker image (if applicable)
docker build -t app:${VERSION} .

# Package artifacts
tar -czf dist-${VERSION}.tar.gz dist/

3. Tag release

Create version tag:

# Semantic versioning
git tag -a v${VERSION} -m "Release ${VERSION}"
git push origin v${VERSION}

4. Deploy to environment

Container-based deployment

# Push to registry
docker push registry.example.com/app:${VERSION}

# Update deployment
kubectl set image deployment/app app=registry.example.com/app:${VERSION}

# Or using Helm
helm upgrade app ./charts/app --set image.tag=${VERSION}

Platform-specific deployment

Vercel/Netlify:

vercel --prod
# or
netlify deploy --prod

AWS:

aws s3 sync dist/ s3://bucket-name/
# or
aws ecs update-service --cluster prod --service app --force-new-deployment

Heroku:

git push heroku main

Custom server:

rsync -avz dist/ user@server:/var/www/app/
ssh user@server 'sudo systemctl restart app'

5. Database migrations (if applicable)

If the story artifacts include migration files:

1. Validate: Dry-run migration against staging/production-like environment

   npm run db:migrate:dry-run
   

2. Human approval: Present migration plan for explicit approval

   • Show: tables affected, columns added/removed, data transformations
   • Show: rollback plan
   • This is a mandatory human-in-the-loop checkpoint

3. Apply: Run migration against production

   npm run db:migrate
   

4. Verify: Confirm schema is correct

   npm run db:status
   

5. On failure: Execute rollback migration immediately

   npm run db:migrate:rollback
   

   Then halt deployment and escalate.

Critical: Production migrations must be applied AFTER merge and DURING deployment, never before merge. Applying migrations before merge creates a window where production schema doesn't match running code.

6. Verify deployment

Confirm deployment succeeded:

verification:
  - check: "Health endpoint responds"
    command: "curl -f https://app.example.com/health"
    expected: "200 OK"

  - check: "Version matches"
    command: "curl https://app.example.com/version"
    expected: "${VERSION}"

  - check: "Key functionality works"
    command: "npm run smoke-test"
    expected: "All smoke tests pass"

7. Handle failure

If deployment fails:

rollback:
  trigger: "Health check fails after 3 attempts"
  actions:
    - "Revert to previous version"
    - "Notify team"
    - "Log failure details"

  commands:
    kubernetes: "kubectl rollout undo deployment/app"
    docker: "docker service update --rollback app"
    heroku: "heroku rollback"

Environment configuration

environments:
  staging:
    url: "https://staging.example.com"
    auto_deploy: true
    approval_required: false
    rollback_on_failure: true

  production:
    url: "https://app.example.com"
    auto_deploy: false
    approval_required: true
    rollback_on_failure: true
    notify:
      - "ops-team@example.com"

Output

deploy:
  version: "1.2.3"
  environment: "production"
  status: "success | failed | rolled_back"

  timeline:
    started: "2024-01-15T10:00:00Z"
    completed: "2024-01-15T10:05:32Z"
    duration: "5m32s"

  pre_checks:
    - name: "tests"
      status: "pass"
    - name: "build"
      status: "pass"

  artifacts:
    - type: "docker_image"
      location: "registry.example.com/app:1.2.3"
    - type: "source_map"
      location: "s3://artifacts/app-1.2.3-sourcemaps.tar.gz"

  verification:
    health_check: "pass"
    version_check: "pass"
    smoke_tests: "pass"

  url: "https://app.example.com"
  commit: "abc123def"
  deployed_by: "orchestrator"

  notes: ""

Update manifest:

releases:
  - version: "1.2.3"
    environment: "production"
    date: "2024-01-15T10:05:32Z"
    stories: ["US-001", "US-002", "US-003"]
    status: "deployed"

Deployment strategies

Blue-green deployment

strategy: "blue-green"
process:
  - Deploy to inactive environment (green)
  - Run verification tests
  - Switch traffic from blue to green
  - Keep blue as rollback target

Canary deployment

strategy: "canary"
process:
  - Deploy to canary (small % of traffic)
  - Monitor for errors
  - Gradually increase traffic
  - Full rollout or rollback based on metrics

Rolling deployment

strategy: "rolling"
process:
  - Update instances one at a time
  - Verify each instance before proceeding
  - Maintain availability throughout

Notifications

notifications:
  on_start:
    - channel: "slack"
      message: "🚀 Deploying v${VERSION} to ${ENV}"

  on_success:
    - channel: "slack"
      message: "✅ v${VERSION} deployed to ${ENV}"
    - channel: "email"
      recipients: ["team@example.com"]

  on_failure:
    - channel: "slack"
      message: "❌ Deployment failed: ${ERROR}"
    - channel: "pagerduty"
      severity: "high"

Tips

• Always deploy to staging first
• Have a rollback plan before deploying
• Monitor closely after production deploys
• Keep deployments small and frequent
• Automate as much as possible
• Document any manual steps required