System Migration Runbook Template

At least one week before the migration window. This gives you time for a staging rehearsal, team review, and revisions based on what you learn during the rehearsal. For large migrations (multi-day or multi-team), start the runbook two weeks out. The [Technical PM Handbook](/technical-pm-guide) covers how to plan migration timelines.

Yes. Every migration step that changes state (data, configuration, DNS, feature flags) must have a documented rollback. There may be a point of no return (e.g., after a destructive schema change), but that point should be explicitly identified in the runbook so the team knows when they have passed it.

Gradual migrations (dual-write, feature flags, canary routing) are safer and preferred for any system serving production traffic. Big-bang migrations are acceptable only when the system can tolerate a maintenance window and the data volume is small enough to migrate within that window. Use [feature flags](/templates) to control the cutover.

The runbook should define a timeout threshold. If the migration exceeds that threshold, the default action is to roll back, not to keep going. Extend the window only if you can clearly identify why it is taking longer and the remaining steps are low-risk. Never extend into business hours without stakeholder approval.

The migration lead makes the call. They should not need to consult a committee during a live migration. Define the rollback criteria in advance (error rate thresholds, data validation failures, duration limits) so the decision is objective, not political. ---