# Deployment Runbook

> 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

1. Declare an incident and name a lead
2. Communicate: who tells customers, and through which channel
3. Escalation contacts: _______________
4. 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 | | |