Skip to main content
A runbook is a step-by-step operational guide for handling a specific task or failure scenario—restarting a service, failing over a database, rotating a certificate. It is written so that any qualified responder can execute it correctly under pressure, without needing the tribal knowledge of the person who wrote it. Good runbooks turn 3 a.m. panic into a checklist.

​
What does a good runbook contain?

A runbook is only as useful as it is followable at the worst possible moment. The strong ones share a structure:
  • Trigger conditions. When to use this runbook—the alert names, symptoms, or dashboards that point here.
  • Preconditions and access. What permissions, tools, or credentials the responder needs before starting, so step 4 isn’t where they discover they lack production access.
  • Numbered steps with exact commands. Copy-pasteable commands, real hostnames or clear placeholders, and the expected output of each step so responders know whether it worked.
  • Verification. How to confirm the fix took—which metric should recover, which endpoint should return 200.
  • Rollback and escalation. What to do if a step fails, and who to page when the runbook runs out.
  • Ownership and last-reviewed date. A runbook nobody has touched in two years is a liability wearing the costume of an asset.
The test is simple: could a competent engineer who has never touched this system follow it end to end? If a step says “restart the service the usual way,” it fails the test.

​
How is a runbook different from documentation?

Documentation explains how a system works; a runbook tells you what to do right now. Architecture docs, API references, and design documents are optimized for understanding—they reward slow, careful reading. Runbooks are optimized for execution—they reward scanning, and they assume the reader is stressed, possibly half-asleep, and not in a mood to learn. A page that starts with three paragraphs of background on the caching layer is documentation; a page that starts with “Step 1: check whether the cache hit rate on this dashboard is below 60%” is a runbook. Teams need both, but mixing them produces something that serves neither purpose well. Closely related is the playbook—a broader response plan that may reference several runbooks. In Rootly, playbooks attach step-by-step guidance directly to matching incidents. The distinction is covered in runbook vs playbook.

​
What is the runbook automation spectrum?

Runbooks evolve along a spectrum from human-executed to fully automated:
  1. Manual. A human reads each step and performs it by hand. This is where every runbook starts, and it’s where you learn whether the steps are actually correct.
  2. Semi-automated. The tedious or error-prone steps become scripts or one-click actions, but a human still decides when to run them and reviews the results. Most operational runbooks should live here for a while—automation with human judgment at the decision points.
  3. Fully automated. The system detects the condition and executes the remediation with no human in the loop—auto-scaling, automatic failover, self-healing restarts. At this point the runbook has effectively graduated into software, and it needs the same testing and review as any other production code.
The spectrum is a maturity path, not a ranking: some procedures (say, anything involving irreversible data operations) should deliberately stay manual or semi-automated. The rule of thumb: automate a step only after it has been executed manually enough times that you trust it completely, and keep the human at every step where judgment beats speed.

​
What does a runbook look like in practice?

Consider a “primary database failover” runbook. It names the triggering alerts (db-primary-unreachable), lists required access (production SSH plus the dba role), then walks through: confirm the primary is truly down (with the exact health-check command and expected failure output), verify replica lag is under 10 seconds, run the promotion script, update the connection string, and watch the error-rate dashboard recover. It ends with an escalation line—“if replica lag exceeds 10 seconds, stop and page the DBA on-call”—that saves a responder from turning an outage into data loss. Browse all definitions in the incident management glossary.