A bad production deployment without a documented rollback plan means your team is improvising under pressure during an outage — when clarity matters most. Database schema changes and infrastructure shifts cannot be undone by git revert alone. Without step-by-step rollback coverage for code, database, and infrastructure (SOC 2 A1.3, NIST CP-10), teams routinely extend incidents from minutes to hours. ISO 25010 reliability.recoverability requires demonstrable recovery procedures, not tribal knowledge.
Critical because the absence of a documented rollback procedure converts every failed deployment into an extended incident where recovery time depends entirely on who is online and what they remember.
Create DEPLOYMENT.md or RUNBOOK.md at the repo root with explicit steps for reverting code, database migrations, and infrastructure changes.
# Rollback Procedure
## Code Rollback (~5 minutes)
1. Identify the previous stable tag or commit hash
2. Redeploy: `git revert <bad-commit>` then push, or trigger re-deploy from prior tag
3. Verify health check at `/api/health` returns 200
## Database Rollback (~15 minutes)
1. Run: `npx prisma migrate resolve --rolled-back <migration-name>`
2. Restore from backup snapshot taken at deployment time if schema is incompatible
3. Confirm critical queries return expected data
## Infrastructure Rollback (~20 minutes)
1. Revert IaC change: `terraform apply -target=<resource>`
2. Confirm routing and load balancer state
Include estimated times — they set expectations during an active incident.
ID: deployment-readiness.ci-cd-pipeline.rollback-documented
Severity: critical
What to look for: Enumerate every relevant item. Look for documentation in README.md, docs/, CONTRIBUTING.md, or a dedicated RUNBOOK.md or DEPLOYMENT.md file. The rollback procedure should explicitly cover reverting code, database schema, and infrastructure changes. It should include estimated rollback time.
Pass criteria: At least 1 of the following conditions is met. Documented rollback procedure exists and covers code reversion (git revert, re-deploy previous version), database rollback (migration reversal, backup restoration), and infrastructure reversion (if applicable). Before evaluating, extract and quote the relevant configuration or code patterns found. Report the count of items checked even on pass.
Fail criteria: No rollback documentation found, or documentation exists but only covers code reversion (missing database or infrastructure reversion steps).
Do NOT pass when: The item exists only as a placeholder, stub, or TODO comment — partial implementation does not count as passing.
Skip (N/A) when: The project is not planned for production deployment, or deployment is fully managed by a third-party platform with no rollback access (e.g., Vercel auto-deployment).
Cross-reference: For deployment and infrastructure concerns, the Deployment Readiness audit covers production configuration.
Detail on fail: "No rollback procedure documented in repository. No RUNBOOK or DEPLOYMENT guide found." or "Rollback documentation covers code reversion only, missing database migration rollback steps."
Remediation: Create a DEPLOYMENT.md or RUNBOOK.md file in your repository documenting the full rollback process:
# Rollback Procedure
## Code Rollback (5 minutes)
1. Identify the previous stable commit hash
2. Deploy previous version: `git revert <bad-commit>` or redeploy from tag
3. Verify health check endpoint returns 200
## Database Rollback (estimated 15 minutes)
1. Restore database from backup snapshot taken at deployment time
2. Run schema rollback migration: `npm run migrate:rollback`
3. Verify critical queries return expected data
## Infrastructure Rollback (estimated 20 minutes)
1. Revert infrastructure changes via IaC: `terraform apply -target=...`
2. Verify routing and load balancer state