Setup Staging Environment and Deployment Pipeline

Problem

Currently, the project only has a production environment. This means:

• All changes go directly to production after merging to main
• No way to test features in a production-like environment before release
• Risk of deploying bugs or breaking changes to production
• No safe space for QA or integration testing

Proposed Solution

Implement a staging environment with a dedicated branch and deployment pipeline:

Development → Staging → Production
   (dev)      (staging)    (main)

Requirements

1. Git Branch Strategy

New Branch Structure

main          → Production environment (protected)
  ↑
staging       → Staging environment (protected)
  ↑
feature/*     → Development branches

Branch Rules

• staging branch:

  • Protected branch
  • Requires PR reviews before merge
  • Auto-deploys to staging environment
  • Used for QA and integration testing

• main branch:

  • Protected branch
  • Only accepts PRs from staging
  • Requires approval + passing tests
  • Auto-deploys to production

2. Environment Configuration

Staging Environment Specs

• Separate database instance (staging data)
• Separate GitHub App credentials (or same with rate limit monitoring)
• Environment variables:

  NODE_ENV=staging
  DATABASE_URL=<staging-db-url>
  GITHUB_TOKEN=<staging-token>
  API_KEY=<staging-api-key>
  PORT=3000
  

Production Environment Specs

• Production database
• Production GitHub App credentials
• Environment variables:

  NODE_ENV=production
  DATABASE_URL=<prod-db-url>
  GITHUB_TOKEN=<prod-token>
  API_KEY=<prod-api-key>
  PORT=3000
  

3. Infrastructure

Choose deployment platform (select one):

Option A: Docker + Cloud Provider

• Create Dockerfile.staging and Dockerfile.prod
• Setup Docker Compose for local staging simulation
• Deploy to cloud provider (AWS/GCP/Azure)
• Configure separate instances for staging and production

Option B: Heroku/Railway/Render

• Create staging app instance
• Create production app instance
• Configure environment variables per instance
• Setup auto-deploy from branches

Option C: Kubernetes

• Create staging namespace
• Create production namespace
• Setup separate ingress rules
• Configure ConfigMaps and Secrets per environment

4. CI/CD Pipeline

GitHub Actions Workflow

File: .github/workflows/staging.yml

name: Deploy to Staging

on:
  push:
    branches: [staging]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test
      - name: Build
        run: npm run build
      - name: Deploy to Staging
        run: |
          # Deploy script here
        env:
          DATABASE_URL: ${{ secrets.STAGING_DATABASE_URL }}
          GITHUB_TOKEN: ${{ secrets.STAGING_GITHUB_TOKEN }}

File: .github/workflows/production.yml

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test
      - name: Build
        run: npm run build
      - name: Run database migrations
        run: npm run migration:run
        env:
          DATABASE_URL: ${{ secrets.PRODUCTION_DATABASE_URL }}
      - name: Deploy to Production
        run: |
          # Deploy script here
        env:
          DATABASE_URL: ${{ secrets.PRODUCTION_DATABASE_URL }}
          GITHUB_TOKEN: ${{ secrets.PRODUCTION_GITHUB_TOKEN }}

5. Database Management

Staging Database

• Create separate PostgreSQL instance for staging
• Setup automated backups
• Option to refresh from production snapshot (sanitized data)
• Run migrations automatically on staging deploy

Production Database

• Keep existing production database
• Backup before each deployment
• Run migrations only after staging validation

6. Environment-Specific Configuration

File: src/config/environment.ts

export const config = {
  environment: process.env.NODE_ENV || 'development',
  isProduction: process.env.NODE_ENV === 'production',
  isStaging: process.env.NODE_ENV === 'staging',
  database: {
    url: process.env.DATABASE_URL,
    ssl: process.env.NODE_ENV !== 'development',
  },
  github: {
    token: process.env.GITHUB_TOKEN,
  },
  api: {
    key: process.env.API_KEY,
  },
  logging: {
    level: process.env.NODE_ENV === 'production' ? 'error' : 'debug',
  },
};

7. Workflow Process

1. Developer creates feature branch from staging
   git checkout -b feature/new-feature staging

2. Developer submits PR to staging
   PR: feature/new-feature → staging

3. After approval, merge to staging
   → Automatically deploys to staging environment
   → QA team tests on staging

4. After validation, create PR from staging to main
   PR: staging → main

5. After approval, merge to main
   → Automatically deploys to production

8. Monitoring and Logging

• Setup separate logging for staging vs production
• Configure error tracking (Sentry/LogRocket) per environment
• Health check endpoints per environment
• Alert configurations (production only for critical issues)

9. Documentation Updates

Files to create/update:

• docs/deployment.md - Deployment process
• docs/environments.md - Environment configuration guide
• README.md - Update with staging info
• .env.example - Add staging-specific variables
• CONTRIBUTING.md - Update PR workflow

Implementation Checklist

Phase 1: Branch Setup

• Create staging branch from current main
• Setup branch protection rules
• Configure PR templates

Phase 2: Infrastructure

• Provision staging server/instance
• Setup staging database
• Configure environment variables
• Test connectivity

Phase 3: CI/CD

• Create GitHub Actions workflows
• Setup secrets in GitHub
• Test deployment to staging
• Test deployment to production

Phase 4: Testing

• Deploy test feature to staging
• Validate database migrations
• Test API endpoints
• Promote to production

Phase 5: Documentation

• Write deployment guide
• Update README
• Document environment variables
• Create runbook for common issues

Success Criteria

• Staging environment deployed and accessible
• Automatic deployments working for both environments
• Database migrations run successfully
• Tests pass on both environments
• Team can access staging for testing
• Production deploys only from staging branch
• Documentation complete

Questions to Answer

1. Which cloud provider/platform to use?
2. What's the staging database refresh strategy?
3. Who has access to staging vs production?
4. What's the rollback strategy for production?
5. Do we need a separate domain for staging?

Estimated Effort

3-5 days depending on infrastructure complexity

Priority

High - Essential for safe production deployments

Labels

infrastructure, devops, ci-cd, enhancement

Related Issues

• #[issue-number] - Add documentation
• #[issue-number] - Setup monitoring

References

• GitHub Actions Documentation
• NestJS Deployment Guide
• Database Migration Best Practices