Rollback Playbook (Netlify)

When a deploy causes issues, use this playbook to roll back safely. It covers the two-site setup (frontend + backend on Netlify) and database considerations.

---

When to roll back

• Frontend: Broken UI, auth errors, wrong API URL, or critical client-side bugs after a deploy.
• Backend: Health check failing, 5xx errors, or broken API endpoints after a deploy.
• Database: Only roll back migrations if you have a verified backup and a tested rollback migration. Prefer fixing forward when possible.

---

1. Roll back on Netlify (site-level)

Each Netlify site keeps deploy history. Rollback reverts that site to a previous deploy; it does not change the repo or the other site.

Frontend site

1. In Netlify: open the frontend site.
2. Go to Deploys.
3. Find the last known-good deploy (e.g. the one before the bad deploy).
4. Click the ⋯ menu on that deploy → Publish deploy (or Restore).
5. Confirm. The site will serve that deploy immediately.

Backend site

1. Open the backend site in Netlify.
2. Go to Deploys.
3. Find the last known-good deploy.
4. ⋯ → Publish deploy (or Restore).
5. Confirm.

Note: Rollback only changes the deployed code. Environment variables (e.g. DATABASE_URL, NEXT_PUBLIC_API_URL) are unchanged. If the incident was caused by an env change, fix the env in Site settings → Environment variables and trigger a new deploy instead of (or after) rollback.

---

2. Database considerations

• No migrations in this deploy: Rolling back frontend/backend is enough; no DB action.
• Migrations were run in the bad deploy:
  • If the new code is rolled back but the DB was already migrated, the old code may be incompatible with the new schema. Options:
    • Preferred: Deploy a fix forward (new code that works with current schema) rather than rolling back code.
    • If you must roll back code: Ensure you have a rollback migration that reverts the schema changes, and run it against the same DB (e.g. npx prisma migrate deploy after reverting the migration files in the repo). Test this in staging first.
  • Backup: For destructive or risky migrations, take a DB snapshot/backup before deploying.

---

3. After rollback

1. Verify:
   • Frontend: open the app, sign in, hit the dashboard.
   • Backend: BACKEND_URL=https://your-backend.netlify.app npm run pre-deploy-check
2. Communicate: If users were affected, notify them (status page, email, or in-app).
3. Post-mortem: Identify root cause, fix in a branch, and deploy again when ready. Avoid rolling back and forgetting.

---

4. Optional: block bad deploys with smoke check

To catch issues before or right after deploy:

• Add BACKEND_URL (and optionally REQUIRE_DB) to repo Secrets in GitHub.
• Run the Smoke check (backend) workflow from the Actions tab (manual Run workflow) after each deploy, or enable the push/schedule triggers in .github/workflows/smoke-check.yml.

If the smoke check fails, investigate before considering the deploy "done"; roll back if the deploy is already live and broken.

---

Quick reference

| Step | Action | |------|--------| | 1 | Netlify → correct site (frontend or backend) → Deploys | | 2 | Pick last known-good deploy → ⋯ → Publish deploy | | 3 | Fix env vars if they caused the issue; avoid rolling back DB unless you have a tested rollback migration | | 4 | Run npm run pre-deploy-check with BACKEND_URL set to confirm backend | | 5 | Post-mortem and fix forward |