Runbook template with an example (alerts and deployments)
A free runbook template for alerts and deployments: what to include, a filled-in example, how to keep runbooks current, and how AI agents can use them.
The page fires at 3 a.m.: checkout-api p99 latency > 2s. The engineer on call has never touched the checkout service. They open the alert, find no link, search the wiki, find three pages from different years, and spend twenty minutes working out what the last person did. The fix takes two.
A runbook is the twenty minutes, written down in advance. This guide gives a template and an example, drawing on Google's SRE book, checked on 16 November 2026.
Why runbooks matter
Google's SRE book says that when humans have to respond, thinking through and recording best practices ahead of time in a playbook produces roughly a 3x improvement in mean time to repair compared with "winging it." It adds that no playbook substitutes for engineers who can think on the fly, but clear troubleshooting steps help most when a page is urgent.
Alert runbook template
One runbook per alert, linked from the alert itself:
# Runbook: [Alert name]
Owner: [Team or person] Last reviewed: [Date] Last used: [Date]
## What this alert means
[What fired, the threshold, and the likely user impact.]
## Severity
[Page now / next business day / informational]
## Confirm it's real
1. [Dashboard link and what to look for]
2. [Query or command to run]
## Mitigate
1. [First safe step, with the exact command]
2. [Next step]
3. [If that fails]
## Verify recovery
- [What normal looks like, and where to check]
## Escalate
- When: [Condition, e.g. not mitigated in 30 minutes]
- Who: [Team, rotation, or person]
## Context
- Known causes: [Past causes, with incident links]
- Related runbooks: [Links]
- Don't: [Actions that make it worse]
Filled-in example
# Runbook: checkout-api p99 latency > 2s
Owner: Payments team Last reviewed: 2026-10-20
## What this alert means
99th percentile latency for checkout-api has been over 2 s for
5 minutes. Customers see slow or failed checkouts.
## Severity
Page now.
## Confirm it's real
1. Open the checkout-api dashboard. Check p99 and error rate.
2. Check the status page of the payment provider.
## Mitigate
1. If the payment provider is degraded: enable the fallback provider
flag `payments.fallback_enabled`. Recovery within 2 minutes.
2. If database CPU is above 90%: check for a running migration
with the query in Context; cancel it if it isn't critical.
3. If a deploy went out in the last 30 minutes: roll back with
`deploy rollback checkout-api`.
## Verify recovery
- p99 under 800 ms for 10 minutes; error rate under 0.5%.
## Escalate
- Not mitigated in 30 minutes: page the payments secondary.
- Provider outage over 1 hour: notify support lead for status page.
## Context
- Known causes: provider outages (#198), locking migration (#212).
- Don't: restart all pods at once; it drops in-flight payments.
Deployment runbook template
# Runbook: Deploy [service]
## Before
- [ ] Change approved and linked: [PR]
- [ ] Migrations reviewed for locking operations
- [ ] Not in a freeze window
## Deploy
1. [Command]
2. [Watch these dashboards for 15 minutes]
## Roll back
1. [Command]
2. [Data steps, if any]
## After
- [ ] Announce in [channel]
- [ ] Close the change ticket
Keeping runbooks alive
A wrong runbook is worse than none, because people trust it.
- Link from the alert. If it isn't one click away, it won't be used at 3 a.m.
- Review after every use. Add an action item to the postmortem: "update the runbook."
- Give it an owner and a last-reviewed date.
- Practice. The SRE book describes exercises such as the "Wheel of Misfortune" to prepare engineers for on-call events.
- Write commands exactly. Copy-pasteable beats described.
Runbooks and AI agents
A precise runbook is something an AI agent can follow too, for diagnosis at least: gather the dashboards, run the read-only queries, summarize what it finds. Keep any step that changes production behind human approval, and remember that a runbook encodes decisions, such as "never restart all pods at once," that an agent needs to know before it acts. See Claude Code permissions.
Where Lockstep fits
Runbooks capture operational decisions; many more live in incident threads and postmortems. Lockstep captures those decisions from documents, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions on the ones that apply, so an agent writing the next migration knows the team decided against locking operations.
See how it works.
Sources checked 16 November 2026
Related reading
For writing up incidents, see the blameless postmortem template. For recording operational decisions, see architecture decision record examples. For getting new engineers on call, see the engineering onboarding checklist. For the overall process, see the incident response plan template. For managing kill switches, see feature flag best practices.
Frequently asked questions
- What is a runbook?
- A written procedure for a specific operational situation: responding to an alert, deploying a service, rotating a credential, or restoring from backup. It lists the steps so whoever is on call can act quickly and consistently, without relying on memory.
- Why are runbooks worth writing?
- Google's SRE book reports that thinking through and recording best practices ahead of time in a playbook produces roughly a 3x improvement in mean time to repair compared with winging it. It also notes no playbook replaces engineers who can think on the fly.
- What is the difference between a runbook and a playbook?
- The terms overlap and many teams use them interchangeably. Where they're separated, a runbook is usually step-by-step instructions for one task, and a playbook covers a broader situation, such as a whole incident type, possibly pointing to several runbooks.
- What should an alert runbook include?
- What the alert means and its impact, how to confirm it's real, the dashboards and logs to check, mitigation steps in order, how to verify recovery, when and how to escalate, and links to past incidents.
- How do I keep runbooks up to date?
- Link each one from its alert, review it after every incident where it was used, give it an owner, and test it in practice exercises. Google's SRE team uses exercises like its Wheel of Misfortune to prepare on-call engineers.
Keep reading