Unclassified

P0: OAuth Production Deployment — Runbook

Status: Execute ONLY after test deployment passes all validation checks
Risk Level: MEDIUM — enables public API for external clients
Rollback Time: ~5 minutes

Prerequisites

MUST complete before proceeding:

Test deployment passed all validation checks (see P0_OAUTH_TEST_DEPLOYMENT_CHECKLIST.md)
Successful test workflow URL captured (e.g., integratewise/integratewise-live/actions/runs/12345)
No critical production incidents in last 24 hours
Release team member on-call for monitoring

Step 1: Configuration Change

Update production environment to enable OAuth:

File: services/mcp-connector/wrangler.toml

Change:

[env.prod.vars]
...
MCP_EXTERNAL_OAUTH_ENABLED = "false"  # ← CHANGE THIS

To:

[env.prod.vars]
...
MCP_EXTERNAL_OAUTH_ENABLED = "true"   # ← Enable for production

Commit:

git add services/mcp-connector/wrangler.toml
git commit -m "P0: Enable public OAuth for production connector platform

- Enables MCP_EXTERNAL_OAUTH_ENABLED in production environment
- User membership binding to Descope auth (removes Customer Zero hard-coding)
- Test validation: <URL to successful test workflow>

This enables external clients to access the public MCP connector interface
with proper tenant membership authorization."

Push:

git push origin release/public-connector-go-live

Step 2: Dry-Run Validation

Always do a dry-run first to catch any configuration issues:

Command:

pnpm release:core \
  --env prod \
  --service core \
  --dry-run true

Expected Output:

✓ All 10 services validated for production deployment
✓ No secrets missing
✓ All service bindings correct
✓ wrangler.toml [env.prod] correctly configured

If fails: Do NOT proceed. Debug and re-run dry-run.

Step 3: Production Deployment

Execute the live deployment with mandatory confirmation:

Command:

pnpm release:core \
  --env prod \
  --service core \
  --dry-run false \
  --confirm_production true \
  --test_release_evidence "<URL to successful test workflow>"

Replace <URL> with:
Example: https://github.com/integratewise/integratewise-live/actions/runs/12345

The workflow will:

Verify test workflow URL is valid and successful
Deploy all 10 services to production
Cloudflare DNS switches to new Workers
Existing traffic flows to new version

Monitor: Watch GitHub Actions for all services reporting "✓ Published"

Step 4: Production Smoke Tests (First 10 Minutes)

Immediately after deployment, verify critical paths:

Test 1: OAuth Metadata Available

curl https://mcp.integratewise.ai/.well-known/oauth-authorization-server | jq '.integratewise_availability'

Expected: "enabled"

Test 2: Connector Catalog Loads

curl https://mcp.integratewise.ai/.well-known/oauth-protected-resource | jq '.resource'

Expected: "https://mcp.integratewise.ai"

Test 3: Customer Zero Still Works

Verify existing internal clients are unaffected:

# Using test OAuth token with Customer Zero tenant
curl -H "Authorization: Bearer <test-jwt>" https://mcp.integratewise.ai/tools

Expected: 200 with 19 Continuity Bridge tools

Test 4: Authorization Flow Renders

curl "https://mcp.integratewise.ai/oauth/authorize?response_type=code&client_id=test&redirect_uri=https://example.com/callback&scope=mcp:tools"

Expected: 200 HTML (consent form)

Step 5: Monitoring (First Hour)

Watch these metrics in Cloudflare Workers dashboard:

Metric	Threshold	Action
5xx errors	> 0.5%	Page on-call + check logs
401 responses	Normal	OAuth challenge is expected
OAuth token endpoint latency	< 500ms	Check JWT signing performance
Request rate to /oauth/*	Expected growth	Normal for new availability

Logs to check:

# MCP-Connector errors
wrangler tail integratewise-mcp-connector --env prod

# Gateway auth errors (tenant binding)
wrangler tail integratewise-gateway --env prod

Step 6: External Client Proof-of-Concept (After 1 Hour)

Once production is stable, test with external client (Task 8):

Create blank v0 application
Add IntegrateWise OAuth connector → redirects to https://mcp.integratewise.ai/oauth/authorize
User goes through Descope login + consent
v0 app receives code + exchanges for token
v0 app queries https://mcp.integratewise.ai/tools with token

Success: External client reads workspace + connector catalog without any provider credentials.

Rollback Procedures

Quick Rollback (< 5 minutes)

If critical errors detected:

# 1. Revert wrangler.toml
git revert <commit-hash>

# 2. Push to prod
git push origin release/public-connector-go-live

# 3. Dry-run
pnpm release:core --env prod --service core --dry-run true

# 4. Deploy disabled
pnpm release:core \
  --env prod \
  --service core \
  --dry-run false \
  --confirm_production true \
  --test_release_evidence "<URL>"

Verification:

curl https://mcp.integratewise.ai/.well-known/oauth-authorization-server | jq '.integratewise_availability'
# Should return: "private_alpha"

Full Rollback (if issues persist)

Roll back entire release to previous commit
Page on-call for incident review
Do not re-attempt without root cause analysis

Success Criteria

Deployment is successful when:

All 10 services report "✓ Published" in GitHub Actions
OAuth metadata endpoint shows availability: "enabled"
Customer Zero clients still work (no regression)
Authorization flow renders correctly
Token exchange succeeds with valid credentials
External client proof-of-concept works (Task 8)
No 5xx errors in first hour
Monitoring metrics normal

Post-Deployment: Marketplace Readiness

After 24 hours of successful production operation:

Publish IntegrateWise MCP Connector Package (P4)
- Make MCP connector discoverable in marketplace
Publish AI Surface Connector Package (P4)
- Enable language models to use IntegrateWise tools
Enable Marketplace Catalog (P4)
- 65+ connectors now visible with release states
- Mark validated connectors as "Available"
- Mark tested-but-pending as "Beta"

Contacts

Release Lead: [Team Member]
On-Call Monitor: [Team Member]
Incident Escalation: [Manager]

Deployment Record

Phase	Date/Time	Status	Notes
Test Deployment
Prod Dry-Run
Prod Deployment
Smoke Tests Pass
24h Monitoring
Marketplace P4 Start