How to Hand Off a Production Deployment Without Writing a Novel
A good deployment handoff isn't a status update — it's the minimum information someone needs to keep going if something breaks after you log off. Here's the format that actually survives 2 a.m.
At 11:40 p.m. a deploy is half done, the person who started it has a flight in the morning, and the message they leave in the channel is: "pushed the fix, should be fine, ping me if anything's weird." Six hours later something is weird. Nobody knows which migration ran. Nobody knows if the queue worker restarted. The person who could answer is asleep with their phone on airplane mode.
That message wasn't lazy. It was optimized for the wrong thing. It optimized for reassurance — for sounding like everything's under control — instead of for what the next person actually needs, which is the ability to act without guessing.
The handoff is not a status update
A status update tells someone how you feel about the deploy. A handoff tells someone what to do if it goes sideways. Those are different documents, and most handoffs accidentally write the first one when the second one is what's needed at 3 a.m.
The test for a good handoff isn't "does this explain what happened." It's "could a competent person who wasn't in the room execute the next step from this alone." If the answer requires a phone call, the handoff failed before anything broke.
What actually needs to be in it
Not everything you did. Not the backstory of why the bug existed. Just the facts someone needs to keep the system alive or reverse the change cleanly. In practice that's seven things, and all seven fit on one screen.
- Commit or branch — the exact ref that's deployed or about to be, not "the latest fix"
- Migrations — which ran, which are pending, and whether they're reversible
- Services to restart, in order — order matters more than the list itself
- Smoke test — the one command or URL that proves it worked, not a full regression pass
- Rollback — the exact command or ref to go back to, tested if at all possible, not "revert the commit"
- Known caveat — the one thing you're not sure about, stated as a risk, not buried in a paragraph
- Current state and next command — what's true right now, and the literal next thing to type
That last item is the one people skip, and it's the one that matters most when the handoff happens mid-deploy rather than after it. "Current state" is not "deploy is done." It's "migration 0043 has run on the primary, 0044 is written but not applied, worker pods have not been bounced yet." The next person doesn't need your intentions. They need your exact position in the sequence.
A template you can paste into a task or a chat message
DEPLOY HANDOFF — [service name] — [date/time, timezone]
Ref: main @ a3f9c12 (tag: v2.14.1)
Migrations: 0043 applied. 0044 pending — NOT reversible, do not run until DB backup confirmed.
Restart order: 1) api 2) worker 3) scheduler
Smoke test: curl -sf https://api.internal/health/deep — expect 200 and "queue_depth" < 500
Rollback: git checkout v2.14.0 && ./deploy.sh — untested past migration 0043, do not roll back if 0044 has run
Known caveat: worker restart is slow (~90s) under current queue load, don't panic if health check fails once
Current state: api and worker restarted and healthy. Scheduler not yet restarted.
Next command: ./restart.sh scheduler --waitNotice what isn't there. No explanation of why the migration was needed. No apology for the caveat. No paragraph about the meeting where this was decided. Someone executing this at 3 a.m. doesn't need the meeting. They need the next command.
An annotated version of the same handoff, mid-incident
The template above is the calm version — a deploy that mostly went fine. Here's the same shape used when it didn't, written by someone stepping away with the system in a partially recovered state.
DEPLOY HANDOFF — billing-service — Tue 23:52 UTC
Ref: hotfix/webhook-retry @ 7c1e40d (NOT merged to main yet)
Migrations: none for this fix.
Restart order: 1) webhook-worker only. Do not restart api, it's fine.
Smoke test: check Stripe webhook log for retries older than 10 min — should be zero after restart
Rollback: kubectl rollout undo deployment/webhook-worker — takes ~30s, safe at any point
Known caveat: fix reduces retry storm but doesn't stop it — root cause (bad signature check) still needs a real patch tomorrow
Current state: webhook-worker restarted once at 23:40, retry count dropped from ~800 to ~40, still draining
Next command: watch retry count. If it's under 10 by 00:15, done for tonight. If it's climbing, run the rollback above and page on-call.That handoff admits the fix is incomplete. It says so in one line instead of hiding it in hedging language. It gives a number to watch and a threshold that decides the next action, instead of asking the next person to use judgment they don't have context for.
Why the novel version fails
Long handoffs feel more responsible to write. They aren't more useful to read. A wall of prose forces the next person to extract the seven facts themselves, under time pressure, from a document optimized for showing effort rather than enabling action. Every sentence of context they have to parse is a sentence between them and the rollback command.
“The best deployment handoff optimizes for execution under uncertainty, not for making the handler feel informed.”
This is also why a handoff written in a chat thread tends to rot faster than one written into a task. Chat scrolls. Someone reads the handoff at 11:52, three more messages arrive by 11:54, and by 3 a.m. it's buried under an unrelated conversation about someone's dog. A task with the handoff in its description doesn't move. It sits where the work is, next to the due date and whoever's assigned, and it's still the top thing you see when you open it.
The caveat is not optional
Teams that skip the "known caveat" line usually skip it because admitting uncertainty feels like admitting the deploy wasn't ready. But the caveat is the highest-value line in the whole document. It's the difference between the next person treating a symptom as expected and treating it as a new incident. Writing "worker restart is slow, don't panic" costs one sentence and saves someone from paging three more people over something you already knew about.
If you only have time to write one honest sentence before you close the laptop, make it that one. Everything else in the template can be reconstructed from logs and git history. The thing that can't be reconstructed is what you were worried about and didn't have time to fix.
