- Every runbook needs an owner, a last-tested date and the alert or task it answers.
- Write the expected result after each step, so the reader knows whether it worked.
- Say when to stop and escalate. A runbook without an exit keeps people guessing.
- Test it by having someone else run it, and keep it in version control.
What fields should a runbook template have?
A runbook is a written procedure for one job. AWS defines it as "a documented process to achieve a specific outcome" and says the minimum is "a step-by-step text document" (AWS). AWS's guidance also says runbooks should "include guidance on error handling, tools, permissions, exceptions, and escalations in case a problem occurs." The fields below cover all of that. For how a runbook differs from a playbook, see runbook vs playbook.
| Field | What to write | Why it matters |
|---|---|---|
| Title and ID | The task or alert name and a short ID such as RB-014 | Alerts and tickets can link to it by ID |
| Owner | The team that keeps it current | Someone is responsible when it goes stale |
| Last tested | The date someone last ran it start to finish | Readers can judge whether to trust it |
| Applies to | Systems, environments and versions | Stops it being used on the wrong system |
| Alert or trigger | The alert ID, ticket type or schedule that starts it | Ties the runbook to the moment it is needed |
| Desired outcome | What is true when the job is done | Tells the reader when to stop |
| Before you start | Access, tools and checks that confirm the problem | Avoids fixing a problem that is not there |
| Steps | Numbered steps with exact commands and expected results | The core of the runbook |
| Errors, rollback and escalation | What can go wrong, how to undo, whom to page | Keeps a bad step from becoming an outage |
| Record and history | Where to log the work; dated list of edits | Leaves a trail for the next person and the postmortem |
Copyable runbook template
Copy this Markdown into a new file in your runbook repository or wiki. AWS suggests that "a version control repository is a great place to start building your runbook library" and publishes its own short template with fields for runbook ID, description, tools, special permissions, author, last updated date and escalation contact (AWS). The version below adds the outcome, error handling, rollback and a record step.
# Runbook: <task or alert name>
| Runbook ID | Owner | Last tested | Applies to | Alert or trigger |
|------------|-------|-------------|------------|------------------|
| RB-000 | team | YYYY-MM-DD | systems | alert ID or "manual" |
## Desired outcome
What is true when this runbook is done.
## Before you start
- Access and permissions needed
- Tools needed
- Checks that confirm the problem is real
## Steps
1. Step, exact command or console path
Expected result:
2. Step
Expected result:
## If something goes wrong
- Error you may see, and what to do
- Rollback steps for every change above
## Escalate when
- Condition, then page: <who>, or switch to playbook: <name>
## Record
Where to write what you did (ticket, incident channel, change record).
## History
| Date | Change | By |
What sections does a full service runbook need?
The template above is for one task or one alert. Some teams also keep a runbook for a whole service, which collects many of those single-task runbooks. PagerDuty cites Tom Limoncelli, an author and former Google sysadmin, who "recommends seven sections for every runbook" (PagerDuty):
| # | Section | What it holds |
|---|---|---|
| 1 | Service overview | What the service is, why it exists, contacts, how to report bugs |
| 2 | Service build information | How to build the software the service runs |
| 3 | Deployment instructions | How to deploy, and how to build a server from scratch |
| 4 | Common tasks | Step-by-step tasks such as provisioning, with common problems and fixes |
| 5 | Pager playbook | Every monitoring alert and the steps to take when it fires |
| 6 | Disaster recovery plans | How to fail over if a service machine dies |
| 7 | Service level agreement | Uptime goals and recovery targets agreed with customers |
Sections 4 and 5 are where the single-task template on this page fits: one file per task or alert, linked from the service runbook.
Runbook example 1: renewing a TLS certificate
This runbook is an illustration written for this page, not a real company's document. It is a planned task, started by a ticket rather than an alert. PagerDuty uses the same case to explain why runbooks exist: "if your team regularly renews a website's SSL certificate, a runbook for that task gives the operator detailed instructions for completing it correctly and quickly" (PagerDuty).
# Runbook RB-014: Renew the TLS certificate for status.example.com
| Owner: platform team | Last tested: 2026-09-30 | Trigger: ticket 21 days before expiry |
## Desired outcome
A new certificate is live on both load balancers; expiry is at least 60 days away.
## Before you start
- Role "lb-operator" in the cloud console; access to the secret manager
- Check the current expiry date on the certificate dashboard
## Steps
1. Request the new certificate in the certificate manager for status.example.com.
Expected result: status "issued".
2. Attach it to load balancer lb-status-1. Expected result: listener shows new expiry.
3. Load the site and check the expiry date in the browser. Repeat for lb-status-2.
## If something goes wrong
- Validation fails: check the DNS record the manager asks for; page DNS owner.
- Browser shows the old date: re-attach the old certificate, then escalate.
## Escalate when
- The certificate expires in under 3 days and is not renewed: page platform lead.
## Record
Close the ticket with the new expiry date and the change ID.
Runbook example 2: responding to a high error rate alert
This one is also an illustration written for this page. It answers one alert, branches on what the engineer finds, and says exactly when the problem has outgrown the runbook and needs the wider incident playbook.
# Runbook RB-031: Alert api-5xx-high (error rate over 2% for 5 minutes)
| Owner: api team | Last tested: 2026-10-20 | Alert: api-5xx-high |
## Desired outcome
Error rate back under 0.5%, cause recorded in the incident ticket.
## Before you start
- Open the API dashboard linked in the page. If the rate is already under 2%,
note "self-recovered" in the ticket and watch for 15 minutes.
## Steps
1. Check the deploy log: was anything released in the last 30 minutes?
If yes, go to step 2. If no, go to step 3.
2. Roll back the last release with the deploy tool's rollback button.
Expected result: error rate falls within 5 minutes.
3. Check the database dashboard. Connection errors mean go to RB-032.
4. Check the upstream status page for the payment provider.
## If something goes wrong
- Rollback fails: stop, declare an incident, page the API lead.
## Escalate when
- Error rate over 10%, or no cause found in 20 minutes: declare an incident
and switch to the playbook "API outage".
## Record
Incident ticket: time, release ID, what you checked, what fixed it.
Google SRE teams pair every alert with a guide: "whenever an alert is created, a corresponding playbook entry is usually created" (Google SRE workbook). Google calls these playbooks; most other teams call them runbooks.
How do you write and test a runbook?
Start small. AWS suggests picking a process that "is conducted semiregularly, short in number of steps, and has low impact failures," then giving the draft "to a team member" to run and fixing whatever is missing (AWS). PagerDuty's writing rules are to keep it "clear and simple" and to "field test the documented process and update it as needed" (PagerDuty).
Keep runbooks current as systems change. Google's SRE workbook warns that "details in playbooks go out of date at the same rate as production environment changes," and recommends automation when a guide is "a deterministic list of commands that the on-call engineer runs every time a particular alert fires" (Google SRE workbook). The person on call is often the one who finds a stale step, so make editing easy and review edits like code. The on-call rotation guide covers how handoff notes point to the runbooks in use.
Common mistakes with runbook templates
A template only helps if people fill it in the same way every time.
- Steps with no expected result, so the reader cannot tell whether a step worked.
- No rollback, so a step that makes things worse cannot be undone quickly.
- Passwords, tokens or keys pasted into steps instead of a pointer to the secret manager.
- A last-tested date that is years old, or none at all.
- Runbooks stored only on the system they are meant to fix.
- Copying a template from another company without changing the steps to match your own systems.
Are runbooks also a data asset?
They can be, together with the incidents they were used in. AI data buyers have asked Origin for the records of companies that run and defend their own infrastructure: incidents joined to the change that fixed them, configuration history, ordered logs of what happened, and the runbooks, SOC tickets, on-call records and postmortems from the same period. What matters is the runbook version that was in force on the day of each incident, so its edit history counts as much as its current text. The records must cover the company's own infrastructure (a client's only where that client has agreed), and the company must own them. See runbook vs playbook, incident postmortem examples and the hub page for infrastructure and incident records.
Origin is an independent data partner. Your company decides what is shared and signs any license itself, and a buyer may pay Origin when a deal closes.
- Secrets come out first: scan runbooks and their history for keys, tokens and passwords, and rotate any you find (remove secrets from git history).
- Internal hostnames, IP addresses and account IDs are masked or replaced with consistent placeholders.
- Names and phone numbers of owners and escalation contacts become pseudonyms.
- Runbooks written for a client's environment stay out unless that client has agreed.
Does your company hold records like these? See what your data is worth.
Common questions
What is a runbook template?
A runbook template is a fixed layout that every runbook in a team follows: title and ID, owner, last-tested date, the alert or trigger, the desired outcome, prerequisites, numbered steps with expected results, error handling and rollback, escalation, and where to record the work. A shared layout lets anyone find the step they need quickly.
What format should a runbook be written in?
Plain Markdown or a wiki page works for most teams. AWS suggests Markdown in a version control repository, which gives every edit an author and a date. The format matters less than consistency: the same headings in the same order, numbered steps and exact commands that can be copied.
Where should runbooks be stored?
In one central place that stays reachable when production is down, such as a version-controlled repository or a hosted wiki. Link each runbook from the alert that pages for it, so the on-call engineer opens it straight from the page. Avoid keeping the only copy on the system it describes.
Who should own a runbook?
The team that owns the system it covers. Name the team in the runbook, not a single person, so ownership survives people moving on. The owner reviews changes, tests the runbook after big system changes and after any incident where it was used, and updates the last-tested date.
Should every alert have a runbook?
Yes, as a rule. If an alert can page someone, there should be a short guide that says what it means, how to confirm it and what to do. Google SRE teams usually create a playbook entry for each new alert. An alert nobody can write steps for may not need to page at all.
How detailed should a runbook be?
Detailed enough that someone who knows the tools, but not this system, can follow it at night without asking anyone. Give exact commands and expected results. Leave out background that does not change what the reader does; link to architecture documents instead of repeating them.
