Deployment Runbook Template
A fill-in runbook for releasing to production, pre-flight checks, the deploy sequence, what to watch and for how long, rollback with a decision-maker named, and the incident path when rollback is not enough.
Markdown. No sign-up, no email.
Written for the person doing the deploy at 17:00 on a Thursday, not for the person who built the pipeline. Assume they are tired, mildly stressed, and have not read the pull request.
Service: _______________ Owner: _______________ Runbook last reviewed: _______
1. Facts you need before starting#
| Where it runs | |
| How to reach the logs | |
| Dashboard URL | |
| Who is on call | |
| Customer impact if this is down | |
| Deploy usually takes |
2. Pre-flight#
- [ ] CI green on the commit being deployed (not on a later one)
- [ ] Change reviewed and approved
- [ ] Database migration included? yes / no, if yes, see §5
- [ ] Configuration or secret changes needed in the target environment
- [ ] Feature flags set to their intended state
- [ ] Someone else knows this deploy is happening
- [ ] Not deploying into a change freeze
- [ ] Rollback path confirmed for THIS change specifically
Commit / version being deployed: _______________
3. Deploy sequence#
| # | Step | Command / action | Expected result |
|---|---|---|---|
| 1 | |||
| 2 | |||
| 3 |
Point of no return: step ____: after this, rollback means ____________________
Name the irreversible step explicitly. The person deploying should know when they are crossing it, rather than discovering it during the rollback attempt.
4. Verify: before declaring success#
| Check | How | Expected |
|---|---|---|
| Health endpoint | ||
| A real user journey works end to end | ||
| Error rate | at or below baseline | |
| Latency p95 | ||
| Queue depth / job processing | ||
| Logs free of new error classes |
Watch for _____ minutes before walking away. Most deploy-related failures appear within the first few minutes, but the ones caused by a slow cache fill, a scheduled job or a connection pool exhausting appear later. Set the number deliberately for this service.
5. Database migrations#
| Migration is backward compatible with the running code | yes / no |
| Expand-then-contract used | yes / no |
| Estimated runtime on production data volume | |
| Locks taken | |
| Tested against a production-sized copy | yes / no, date |
| Rollback: reverse migration or restore |
A migration that is not backward compatible turns a deploy into a coordinated outage, and makes rollback impossible without data loss. Split it: add the new shape, deploy code that writes both, backfill, switch reads, then remove the old shape in a later release.
6. Rollback#
Decision-maker: _______________ (name a person; "the team" delays the decision)
Trigger conditions, decide these BEFORE deploying:
- Error rate above _____ for _____ minutes
- Latency p95 above _____
- Any data corruption, immediately
- Health checks failing after _____ minutes
Rollback steps:
| # | Step | Expected result |
|---|---|---|
| 1 | ||
| 2 |
Rollback last tested: _______ How long it took: _______
Debugging forward under pressure is how a five-minute rollback becomes a two-hour outage. Roll back first, understand it afterwards, with the pressure off.
7. If rollback does not fix it#
- Declare an incident and name a lead
- Communicate: who tells customers, and through which channel
- Escalation contacts: _______________
- Preserve logs and state before further changes
8. After the deploy#
- [ ] Change log updated
- [ ] Feature flag state recorded
- [ ] Monitoring re-checked after the first full traffic cycle
- [ ] Anything that surprised you added to this runbook
A runbook improves after every use or it decays. Whoever ran this deploy owns the edit.
Review#
| Name | Date | |
|---|---|---|
| Written by | ||
| Last run by | ||
| Next review due |