Runbook best practices haven't changed that much at their core: a good runbook is actionable, accessible, accurate, authoritative, and adaptable. These five attributes separate a runbook your team relies on from one they ignore. What has changed is what happens after you write it. With Harness AI SRE, your runbooks don't just guide responders — they execute automatically, file tickets, trigger rollbacks, and post updates to the incident timeline without anyone manually following a checklist.
What Is a Runbook?
A runbook is a step-by-step guide for performing a task in a system, whether you're seeing it for the first time or coming back after months away. You reach for it during on-call rotations, service disruptions, or when onboarding a teammate.
This article covers runbooks for software systems and incident response automation — not airplanes or surgery.
When to Use a Runbook
Runbooks earn their place whenever a process is too nuanced or variable to fully automate. Even with strong SRE automation, some steps still need human judgment. Runbooks cover that gap — giving you structure without assuming automation handles everything.
Common use cases include:
- Investigating or stabilizing an incident before a full root cause analysis
- Running complex business processes, like generating a monthly billing report
- Handling repetitive but critical dev tasks, like setting up a test environment
Runbook Best Practices: The Five Attributes of a Good Runbook
1. Actionable
A runbook should tell you what to do next. Each task should be:
- Clear, concise, and goal-oriented
- Written for whoever will use it — new hires, mid-level engineers, or senior SREs
- One completable step at a time, with no compound instructions
When someone needs deeper context, link out to reference docs. Keep the runbook focused on action.
Good: SSH into the database server and run tail -f /var/log/db.log
Bad: Log in to the database server, edit the config file, and restart the process.
For incident runbooks, add a follow-up step like an RCA or retrospective so what you learn makes it back into the runbook and your wider operations.
2. Accessible
A runbook nobody can find during an outage might as well not exist.
Make runbooks easy to find:
- Associate them with alerts or services
- Tag them with metadata: type (incident, maintenance, onboarding), creation and last-update timestamps, author or owner, linked systems
- Make them searchable from Slack, your terminal, or your incident tool
In AI SRE, runbooks are pinned to incident types or attached to alert rules so they surface automatically — the right runbook appears at the moment it's needed, with no searching required.
3. Accurate
Outdated runbooks lose people's trust. Lead an engineer down the wrong path once and they won't come back.
Keep runbooks accurate:
- Make updates lightweight, via PRs, comments, or an edit button
- Track both last-updated and last-used timestamps
- Have engineers validate steps before publishing, and copy-paste commands rather than retyping them
- Link usage history, like associated incidents or alerts, where you can
AI SRE logs every runbook execution step by step — inputs, outputs, and status — tied directly to the incident timeline. When a step fails, it shows up in the timeline rather than going unnoticed, making it easy to trace what needs updating.
4. Authoritative
One process, one runbook, no duplicates.
When multiple versions exist, consolidate them and archive the outdated copies. If a section needs to be reused across processes, link to it instead of copying it.
Add a simple way to flag problems. If someone hits a conflicting or misleading step, they should know how to report it.
5. Adaptable
Systems change constantly, and runbooks have to keep up.
- Assign clear ownership per runbook or section
- Open contributions to the team where it makes sense
- Build runbook updates into retrospectives and deployment checklists
- Call out the runbooks that save time or prevent an incident
- Automate the high-confidence sections once you trust them
Treat a broken runbook like a broken test and fix it right away.
Spotting Stale Runbooks
Signs a runbook has gone stale:
- A last-updated timestamp older than 12 months
- No recent use, or no link to a recent incident
- Feedback or comments flagging problems
If it's outdated but still needed, update it. If the system it documents is gone, archive it: mark the title with [ARCHIVED] and move it to a separate folder.
Runbooks in Harness AI SRE
A runbook in AI SRE is a set of steps that execute during an alert or incident. Each step acts on a connected system or on the incident record, and its result is posted to the incident timeline. The same runbook that pages the on-call can also file the ticket and run the Harness pipeline that ships the fix.
This is the part a static runbook document cannot do: it can tell a responder to roll back, but it cannot run the deploy itself. Harness AI SRE closes that gap — transforming your runbook automation from a reference document into an active participant in incident resolution.
How a Runbook Is Built
Each runbook is an ordered chain of steps. A step does one of four things:
- Runs an action against a connected system
- Sets a field on the incident
- Branches on a condition
- Loops over a list
Steps take typed inputs and pass their outputs to later steps. If a step fails, an error path runs. You build runbooks in a visual editor.
Actions a Step Can Call
AI SRE includes built-in actions that a step can call without custom integration work. They cover the systems an incident touches:
- Communication: Slack, Microsoft Teams, Google Chat, Zoom, email, SMS
- Ticketing and paging: Jira, ServiceNow, PagerDuty, Opsgenie, Jira Service Management
- Automation: run a Harness pipeline, toggle a feature flag, set a Harness connector, post an incident review, resolve an alert
Running a Harness Pipeline as a Step
AI SRE has a native step that executes a Harness pipeline. You give the step a pipeline and its input YAML, and it runs your rollback or hotfix deploy inside the incident response. The step checks the caller's pipeline-execute permission, optionally waits for the run to finish, and posts the execution link and status to the incident timeline.
Because Harness owns the CI/CD pipeline, the runbook reaches it directly — no separate integration to configure.
Getting the Right Runbook to the Incident
Two mechanisms put a runbook in front of responders without anyone searching for it (a key incident response automation principle in Harness AI SRE):
- Pinned runbooks: Pin runbooks to an incident type, and they appear for one-click execution whenever that type of incident opens.
- Alert-rule attachment: Attach a runbook to an alert rule with its inputs pre-filled, and it runs automatically when the alert fires.
A runbook can also be set to trigger on incident lifecycle events through a rule condition.
Tracking What Ran
Every runbook execution is logged step by step, with its inputs, outputs, and a status of running, success, or failed. The record is tied to the incident timeline, so a responder can see what ran, when, and what it returned. A step that fails shows up in the timeline rather than going unnoticed.
Bottom Line
Runbooks are an operational safety net. They cut cognitive load and pass institutional knowledge to whoever's on call. Automation keeps growing, but plenty of situations still need a human in the loop — and that human needs clear, current instructions.
Get the five runbook best practices right and your team recovers faster with less on-call stress. Pair them with Harness AI SRE and those runbooks stop being documents people read — they become automated workflows that execute the moment an incident opens, reducing MTTR and keeping your team focused on the work that actually requires human judgment.
All this author’s posts
Ryan Taylor is the Director of Product for AI-SRE at Harness, with 20 years of experience in ProdOps and SaaS innovation.
