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:
- Quality gate (lint, typecheck, test)
- Build with Vercel CLI
- Deploy with
--prodflag - Health check (5 retries, 10s intervals)
- Lighthouse budget check (production only)
- 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:
- Quality gate
- Build
- Deploy without
--prod(gets unique Vercel URL) - Alias to
canary.oshun.app - Health check on canary URL
- 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#
Option 1: GitHub Actions Rollback (Recommended)#
Use the deploy workflow with the rollback URL from a previous deployment.
Steps:
-
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)
-
Trigger rollback:
textGitHub → Actions → OSHUN Web Deploy → Run workflow → Environment: production (or staging) → Strategy: standard → Rollback URL: https://oshun-web-abc123.vercel.app -
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#
- Error monitoring: Check the BFF error reporting dashboard for spikes
- Lighthouse: Review the automated Lighthouse CI results (production only)
- Bundle size: Check the bundle monitor PR comment for regressions
- 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 |