Unclassified

IntegrateWise Deployment & Environment Guide

CI/CD, Release Management, and Infrastructure

Version: 1.0
Classification: Internal Engineering
Last Updated: January 2026

Environment Overview
CI/CD Pipeline
Deployment Process
Release Checklist
Feature Flags
Rollback Procedures
Versioning Policy
Database Migrations
Secret Management

1. Environment Overview

1.1 Environment Summary

Environment	Purpose	URL	Branch
Development	Local development	localhost:3000	feature/*
Preview	PR previews	*.preview.integratewise.com	PR branches
Staging	Pre-production testing	staging.integratewise.com	staging
Production	Live customers	app.integratewise.com	main

1.2 Environment Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                      ENVIRONMENT ARCHITECTURE                                │
└─────────────────────────────────────────────────────────────────────────────┘

     DEVELOPMENT            STAGING                PRODUCTION
     ───────────            ───────                ──────────

     ┌───────────┐         ┌───────────┐         ┌───────────┐
     │  Local    │         │ Cloudflare│         │ Cloudflare│
     │  Dev      │         │  Workers  │         │  Workers  │
     │  Server   │         │ (Staging) │         │ (Prod)    │
     └─────┬─────┘         └─────┬─────┘         └─────┬─────┘
           │                     │                     │
           ▼                     ▼                     ▼
     ┌───────────┐         ┌───────────┐         ┌───────────┐
     │  Local    │         │ Supabase  │         │ Supabase  │
     │  Supabase │         │  Staging  │         │   Prod    │
     │  (Docker) │         │ (Project) │         │ (Project) │
     └───────────┘         └───────────┘         └───────────┘
           │                     │                     │
           ▼                     ▼                     ▼
     ┌───────────┐         ┌───────────┐         ┌───────────┐
     │  Seed     │         │  Staging  │         │  Live     │
     │  Data     │         │  Data     │         │  Data     │
     └───────────┘         └───────────┘         └───────────┘

1.3 Environment Configuration

Config	Development	Staging	Production
Debug mode	Enabled	Enabled	Disabled
Logging level	Debug	Info	Warn
Rate limits	Disabled	Reduced	Full
External APIs	Sandbox	Sandbox	Live
Email sending	Console	Mailtrap	Production
AI providers	Mock/Live	Live	Live

1.4 Environment Variables

# Base configuration
NODE_ENV=production|staging|development
APP_URL=https://app.integratewise.com
API_URL=https://api.integratewise.com

# Database
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_KEY=eyJ...
DATABASE_URL=postgresql://...

# Cloudflare
CF_ACCOUNT_ID=xxx
CF_API_TOKEN=xxx

# External Services
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Feature Flags
ENABLE_AI_FEATURES=true
ENABLE_BETA_FEATURES=false

2. CI/CD Pipeline

2.1 Pipeline Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                         CI/CD PIPELINE                                       │
└─────────────────────────────────────────────────────────────────────────────┘

     COMMIT              BUILD                TEST                DEPLOY
     ──────              ─────                ────                ──────

     ┌─────────┐        ┌─────────┐        ┌─────────┐        ┌─────────┐
     │  Push   │───────▶│  Lint   │───────▶│  Unit   │───────▶│ Preview │
     │  to PR  │        │  Check  │        │  Tests  │        │  Deploy │
     └─────────┘        └─────────┘        └─────────┘        └─────────┘
          │                  │                  │                  │
          │                  ▼                  ▼                  │
          │             ┌─────────┐        ┌─────────┐            │
          │             │  Type   │        │  E2E    │            │
          │             │  Check  │        │  Tests  │            │
          │             └─────────┘        └─────────┘            │
          │                  │                  │                  │
          └──────────────────┴──────────────────┴──────────────────┘

     MERGE TO MAIN                           RELEASE
     ─────────────                           ───────

     ┌─────────┐        ┌─────────┐        ┌─────────┐        ┌─────────┐
     │  Merge  │───────▶│  Build  │───────▶│ Staging │───────▶│  Prod   │
     │  to     │        │  Prod   │        │ Deploy  │        │ Deploy  │
     │  main   │        │  Bundle │        │  + Test │        │         │
     └─────────┘        └─────────┘        └─────────┘        └─────────┘

2.2 GitHub Actions Workflow

# .github/workflows/ci.yml
name: CI/CD Pipeline

on:
  push:
    branches: [main, staging]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "pnpm"
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm typecheck

  test:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "pnpm"
      - run: pnpm install --frozen-lockfile
      - run: pnpm test:unit
      - run: pnpm test:integration
      - uses: codecov/codecov-action@v3

  deploy-preview:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - uses: cloudflare/wrangler-action@v3
        with:
          command: deploy --env preview
          apiToken: ${{ secrets.CF_API_TOKEN }}

  deploy-staging:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - uses: cloudflare/wrangler-action@v3
        with:
          command: deploy --env staging
          apiToken: ${{ secrets.CF_API_TOKEN }}
      - name: Run smoke tests
        run: pnpm test:smoke --env=staging

  deploy-production:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: cloudflare/wrangler-action@v3
        with:
          command: deploy --env production
          apiToken: ${{ secrets.CF_API_TOKEN }}
      - name: Run smoke tests
        run: pnpm test:smoke --env=production

2.3 Pipeline Gates

Gate	Required	Blocking
Lint pass	Yes	Yes
Type check pass	Yes	Yes
Unit tests pass	Yes	Yes
Integration tests pass	Yes	Yes
E2E tests pass	Yes	Yes
Code coverage > 80%	Yes	No (warning)
Security scan clean	Yes	Yes
PR approval	Yes	Yes

3. Deployment Process

3.1 Standard Deployment

# 1. Merge PR to main (triggers auto-deploy to staging)

# 2. Verify staging deployment
pnpm test:smoke --env=staging

# 3. Production deployment (auto-triggered after staging success)
# Manual approval required in GitHub Actions

# 4. Verify production deployment
pnpm test:smoke --env=production

# 5. Monitor for 30 minutes post-deploy

3.2 Deployment Commands

# Preview deployment (from PR)
wrangler deploy --env preview

# Staging deployment
wrangler deploy --env staging

# Production deployment
wrangler deploy --env production

# Rollback to previous version
wrangler rollback --env production

3.3 Zero-Downtime Deployment

Cloudflare Workers provides zero-downtime deployments:

New version is uploaded
Health check validates new version
Traffic gradually shifts to new version
Old version is deprecated after success

┌─────────────────────────────────────────────────────────────────────────────┐
│                      ZERO-DOWNTIME DEPLOYMENT                                │
└─────────────────────────────────────────────────────────────────────────────┘

     Time ─────────────────────────────────────────────────────────────────▶

     Traffic to v1.0: ████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
     Traffic to v1.1: ░░░░░░░░░░░░░░░░░░░░████████████████████████████████████

                      │                   │
                      Deploy v1.1         Cutover complete
                      Health check OK     v1.0 deprecated

4. Release Checklist

4.1 Pre-Release Checklist

## Pre-Release Checklist

### Code Quality

- [ ] All tests passing
- [ ] No lint errors
- [ ] Code review approved
- [ ] Security scan clean
- [ ] Performance benchmarks acceptable

### Documentation

- [ ] CHANGELOG updated
- [ ] API docs updated (if applicable)
- [ ] User docs updated (if applicable)
- [ ] Internal runbook updated (if applicable)

### Database

- [ ] Migration scripts reviewed
- [ ] Migration tested in staging
- [ ] Rollback migration prepared
- [ ] Backup verified

### Feature Flags

- [ ] New features behind flags
- [ ] Flag configuration verified

### Communication

- [ ] Status page prepared (if maintenance)
- [ ] Customer notification drafted (if breaking)
- [ ] Internal team notified

4.2 Release Checklist

## Release Checklist

### Staging Deployment

- [ ] Deploy to staging
- [ ] Run smoke tests
- [ ] Manual QA pass
- [ ] Performance verified

### Production Deployment

- [ ] Obtain deployment approval
- [ ] Deploy to production
- [ ] Run smoke tests
- [ ] Monitor error rates (15 min)
- [ ] Monitor latency (15 min)

### Post-Release

- [ ] Verify all health checks green
- [ ] Check critical user flows
- [ ] Monitor for 30 minutes
- [ ] Update status page (if applicable)
- [ ] Close release ticket

4.3 Emergency Release

For critical fixes:

Create hotfix branch from main
Apply fix with minimal changes
Get expedited review
Deploy directly to production (skip staging)
Backfill staging after production is stable

5. Feature Flags

5.1 Feature Flag System

We use environment-based feature flags:

// lib/flags.ts
  // Gradual rollout flags
  ENABLE_AI_SUGGESTIONS: env.ENABLE_AI_SUGGESTIONS === "true",
  ENABLE_BULK_OPERATIONS: env.ENABLE_BULK_OPERATIONS === "true",

  // Beta flags
  ENABLE_BETA_DASHBOARD: env.ENABLE_BETA_DASHBOARD === "true",
  ENABLE_ADVANCED_AUTOMATIONS: env.ENABLE_ADVANCED_AUTOMATIONS === "true",

  // Kill switches
  ENABLE_EXTERNAL_INTEGRATIONS: env.ENABLE_EXTERNAL_INTEGRATIONS !== "false",
  ENABLE_DOCUMENT_GENERATION: env.ENABLE_DOCUMENT_GENERATION !== "false",
};

// Usage
if (flags.ENABLE_AI_SUGGESTIONS) {
  await generateSuggestions(account);
}

5.2 Flag Types

Type	Purpose	Default	Example
Release	New feature rollout	Off	`ENABLE_NEW_DASHBOARD`
Experiment	A/B testing	Off	`EXPERIMENT_PRICING_V2`
Ops	Operational control	On	`ENABLE_WEBHOOKS`
Kill switch	Emergency disable	On	`ENABLE_AI_PROVIDERS`

5.3 Flag Lifecycle

┌─────────────────────────────────────────────────────────────────────────────┐
│                      FEATURE FLAG LIFECYCLE                                  │
└─────────────────────────────────────────────────────────────────────────────┘

     CREATE              ROLLOUT               CLEANUP
     ──────              ───────               ───────

     ┌─────────┐        ┌─────────┐        ┌─────────┐        ┌─────────┐
     │  Add    │───────▶│  Enable │───────▶│  100%   │───────▶│  Remove │
     │  Flag   │        │  for    │        │  Rollout│        │  Flag   │
     │  (off)  │        │  Beta   │        │         │        │  Code   │
     └─────────┘        └─────────┘        └─────────┘        └─────────┘
          │                  │                  │                  │
          │              Staging           Production         After 30
          │              then Prod         verified           days stable
          ▼                  │                  │                  │
     Development         1-5% users         All users         Cleanup PR

6. Rollback Procedures

6.1 Application Rollback

# Cloudflare Workers rollback (instant)
wrangler rollback --env production

# Or deploy specific version
wrangler deploy --env production --version 2024-01-01-abc123

6.2 Database Rollback

# 1. Identify the migration to rollback
pnpm prisma migrate status

# 2. Rollback migration (if rollback exists)
pnpm prisma migrate resolve --rolled-back "20260107_add_feature"

# 3. Apply rollback SQL
psql $DATABASE_URL -f migrations/rollback/20260107_add_feature.sql

# 4. Update migration state
pnpm prisma migrate resolve --applied "20260106_previous"

6.3 Rollback Decision Matrix

Scenario	Action	Time to Recover
App bug, no data impact	Rollback app	< 5 minutes
Migration issue, no data loss	Rollback migration + app	< 30 minutes
Data corruption	Restore from backup	< 4 hours
Third-party outage	Disable integration	< 5 minutes

6.4 Rollback Runbook

## Rollback Runbook

### Step 1: Assess Impact

- [ ] Identify affected users/features
- [ ] Determine root cause (app vs data)
- [ ] Decide rollback strategy

### Step 2: Communicate

- [ ] Update status page
- [ ] Notify internal team
- [ ] Prepare customer communication (if needed)

### Step 3: Execute Rollback

- [ ] For app issues:
  ```bash
  wrangler rollback --env production
  ```

For database issues:

psql $DATABASE_URL -f migrations/rollback/xxx.sql

Step 4: Verify

Run smoke tests
Check error rates
Verify critical flows
Monitor for 15 minutes

Step 5: Post-Rollback

Update status page (resolved)
Create incident report
Schedule post-mortem


---

# 7. Versioning Policy

## 7.1 Semantic Versioning

We follow SemVer (MAJOR.MINOR.PATCH):

| Change Type | Version Bump | Example |
|-------------|--------------|---------|
| **Breaking API change** | Major | 1.0.0 → 2.0.0 |
| **New feature** | Minor | 1.0.0 → 1.1.0 |
| **Bug fix** | Patch | 1.0.0 → 1.0.1 |

## 7.2 API Versioning

https://api.integratewise.com/v1/accounts
^^
Version prefix


**Version policy:**
- Major versions in URL path (`/v1/`, `/v2/`)
- Breaking changes require new major version
- Old versions supported for 12 months after deprecation

## 7.3 Version Headers

```http
# Response headers
X-API-Version: 2026-01-01
X-App-Version: 1.5.2
X-Request-ID: req_abc123

7.4 Changelog

# Changelog

## [1.5.0] - 2026-01-07

### Added

- Bulk account operations
- Advanced health score components
- Webhook signature verification

### Changed

- Improved sync performance (2x faster)
- Updated dashboard design

### Fixed

- Fixed timezone handling in date filters
- Fixed pagination for large result sets

### Deprecated

- `/v1/metrics` endpoint (use `/v1/health` instead)

8. Database Migrations

8.1 Migration Workflow

# 1. Create migration
pnpm prisma migrate dev --name add_feature

# 2. Review generated SQL
cat prisma/migrations/20260107_add_feature/migration.sql

# 3. Test migration locally
pnpm db:reset
pnpm db:seed

# 4. Create rollback script
# migrations/rollback/20260107_add_feature.sql

# 5. Deploy to staging (auto via CI)
# 6. Verify in staging
# 7. Deploy to production (auto via CI)

8.2 Migration Best Practices

Do	Don't
✅ Add columns as nullable first	❌ Add NOT NULL without default
✅ Use transactions	❌ Mix schema + data changes
✅ Create rollback script	❌ Deploy without testing
✅ Run in low-traffic window	❌ Drop columns immediately
✅ Backfill data separately	❌ Lock tables for long operations

8.3 Zero-Downtime Migration Pattern

-- Step 1: Add nullable column
ALTER TABLE accounts ADD COLUMN new_field TEXT;

-- Step 2: Backfill data (in batches)
UPDATE accounts SET new_field = 'default' WHERE new_field IS NULL LIMIT 1000;

-- Step 3: Add NOT NULL constraint (after backfill complete)
ALTER TABLE accounts ALTER COLUMN new_field SET NOT NULL;

-- Step 4: Add index (concurrently)
CREATE INDEX CONCURRENTLY idx_accounts_new_field ON accounts(new_field);

9. Secret Management

9.1 Secret Storage

Secret Type	Storage	Access
API keys	Cloudflare Workers Secrets	Runtime only
Database credentials	Cloudflare Workers Secrets	Runtime only
OAuth tokens	Database (encrypted)	Application
Webhook secrets	Database (encrypted)	Application

9.2 Adding Secrets

# Add secret to Cloudflare Workers
wrangler secret put SECRET_NAME --env production

# Bulk add from .env
cat .env.production | while IFS='=' read key value; do
  echo "$value" | wrangler secret put "$key" --env production
done

9.3 Secret Rotation

Secret	Rotation Frequency	Process
API keys	90 days	Automated
Database password	180 days	Manual (coordinated)
OAuth client secret	Annually	Manual (coordinated)
Webhook signing keys	On demand	Customer-initiated

9.4 Secret Rotation Runbook

## Secret Rotation Runbook

### Database Password Rotation

1. Generate new password
   ```bash
   openssl rand -base64 32
   ```

Update in Supabase console

Update Cloudflare secret

echo "new_password" | wrangler secret put DATABASE_PASSWORD --env production

Verify connection
```
pnpm test:smoke --env=production
```
Update local .env files (do not commit)


---

**IntegrateWise Deployment & Environment Guide**
*Version 1.0 — January 2026*

For questions: engineering@integratewise.com