Eve library

OSHUN Web — Deployment & Rollback Procedures

Guide

Revision 1

On this page

Environments#

Environment URL Branch Deploy Trigger
Staging staging.oshun.app main Automatic on push
Production oshun.app main Manual workflow dispatch
Canary canary.oshun.app main Manual (canary strategy)
PR Preview oshun-web-pr-*.vercel.app PR Automatic on PR open

Deployment Strategies#

Standard Deployment#

Full-traffic deployment. The new build replaces the current production/staging deployment entirely.

Trigger:

text
GitHub → Actions → OSHUN Web Deploy → Run workflow
  → Environment: production
  → Strategy: standard

Flow:

  1. Quality gate (lint, typecheck, test)
  2. Build with Vercel CLI
  3. Deploy with --prod flag
  4. Health check (5 retries, 10s intervals)
  5. Lighthouse budget check (production only)
  6. Source map upload (automatic via workflow_run trigger)

Canary Deployment#

Deploy to a separate URL without affecting production traffic. Use this to validate changes before promoting to full production.

Trigger:

text
GitHub → Actions → OSHUN Web Deploy → Run workflow
  → Environment: production
  → Strategy: canary

Flow:

  1. Quality gate
  2. Build
  3. Deploy without --prod (gets unique Vercel URL)
  4. Alias to canary.oshun.app
  5. Health check on canary URL
  6. Manual validation before promoting

Promoting canary to production:

After validating the canary, trigger a standard deployment or use the Vercel CLI:

bash
vercel alias set <canary-deployment-url> oshun.app \
  --token=$VERCEL_TOKEN \
  --scope=$VERCEL_ORG_ID

Rollback Procedure#

Use the deploy workflow with the rollback URL from a previous deployment.

Steps:

  1. Find the previous deployment URL:

    • Go to Vercel Dashboard → OSHUN Web project
    • Or check the GitHub Actions run for the last successful deployment
    • Copy the deployment URL (e.g., https://oshun-web-abc123.vercel.app)
  2. Trigger rollback:

    text
    GitHub → Actions → OSHUN Web Deploy → Run workflow
      → Environment: production (or staging)
      → Strategy: standard
      → Rollback URL: https://oshun-web-abc123.vercel.app
    
  3. The workflow will alias the previous deployment to the production domain

Option 2: Vercel CLI Rollback#

bash
# List recent deployments
vercel ls oshun-web --token=$VERCEL_TOKEN

# Promote a specific deployment to production
vercel alias set <deployment-url> oshun.app \
  --token=$VERCEL_TOKEN \
  --scope=$VERCEL_ORG_ID

# For staging
vercel alias set <deployment-url> staging.oshun.app \
  --token=$VERCEL_TOKEN \
  --scope=$VERCEL_ORG_ID

Option 3: Git Revert#

If the issue is in the code and not the deployment infrastructure:

bash
# Revert the problematic commit
git revert <commit-sha>
git push origin main

# This triggers an automatic staging deployment
# Then manually promote to production via the workflow

Post-Rollback Checklist#

After any rollback:

  • Verify the rollback URL is serving correctly
  • Check health endpoint returns 200
  • Verify error monitoring is not showing new errors
  • Notify the team in the appropriate channel
  • Create a post-mortem issue if the deployment caused user-facing issues
  • Investigate root cause before re-deploying

Health Checks#

The deployment workflow runs health checks automatically:

  • Endpoint: Root URL (/)
  • Expected: HTTP 200
  • Retries: 5 attempts with 10-second intervals
  • Stabilization: 15-second wait after deployment before first check

To manually check:

bash
curl -s -o /dev/null -w "%{http_code}" https://oshun.app
curl -s -o /dev/null -w "%{http_code}" https://staging.oshun.app

Monitoring After Deployment#

  1. Error monitoring: Check the BFF error reporting dashboard for spikes
  2. Lighthouse: Review the automated Lighthouse CI results (production only)
  3. Bundle size: Check the bundle monitor PR comment for regressions
  4. Core Web Vitals: Monitor via the Web Vitals reporting endpoint

CI/CD Workflow Summary#

Workflow Trigger Purpose
oshun-web-deploy.yml Push main / manual Build and deploy
oshun-web-preview.yml PR open/update PR preview deployment
oshun-web-e2e.yml PR / push / daily Playwright E2E tests
oshun-web-lighthouse.yml PR Lighthouse performance budgets
oshun-web-bundle-monitor.yml PR / push Bundle size tracking
oshun-web-visual-regression.yml PR Visual snapshot comparison
oshun-web-sourcemaps.yml After deploy success Source map upload for errors

Required Secrets#

Secret Purpose
VERCEL_TOKEN Vercel CLI authentication
VERCEL_ORG_ID Vercel organization scope
OSHUN_WEB_VERCEL_PROJECT_ID Vercel project identifier
OSHUN_PRODUCTION_BFF_URL Production BFF base URL
OSHUN_STAGING_BFF_URL Staging BFF base URL
OSHUN_WEB_SENTRY_DSN Error monitoring DSN
OSHUN_WEB_ANALYTICS_WRITE_KEY Analytics write key
OSHUN_WEB_FEATURE_FLAGS Feature flag JSON
OSHUN_SOURCEMAP_TOKEN Auth token for source map upload