Runbooks

A runbook is your team’s answer to “we’ve seen this before, here’s what to do.” In Firefight, runbooks are structured objects rather than wiki pages: a short summary, a rich procedure written in Markdown, and an ordered list of steps. When an incident matches a runbook’s conditions, the runbook attaches itself and appears in the incident channel, so the procedure finds the responder instead of the responder hunting for the procedure.

Runbooks live at Settings → Runbooks and require workspace admin access to manage.

Anatomy of a runbook

Part	What it is for
Name	What the procedure is called, like “Database failover”
Summary	A short description of when to use it. Shown in listings, in Slack, and to AI agents deciding whether the runbook is relevant
Content	The full procedure, edited with formatting (headings, lists, code blocks) and stored as Markdown
External URL	An optional link to a page elsewhere, like a wiki article or a dashboard, if part of the procedure lives outside Firefight
Steps	An ordered list of discrete actions responders should take, each with a title and instructions

Content and steps play different roles. Content is the narrative: context, decision points, queries to run, things to check. Steps are the checklist: concrete actions that responders can pick up, complete, and track one by one.

Conditions and automatic attachment

Each runbook carries conditions that decide which incidents it applies to. You can match on:

• Incident type, like Production or Security
• Severity, like Critical or Major
• Custom fields, including catalog references, so a runbook can target incidents affecting a specific service, environment, or any other field you have defined

Every condition supports “is one of” and “is not one of”, and an incident must match all conditions for the runbook to attach. A runbook with no conditions attaches to every incident.

Conditions are evaluated when an incident is declared, and again whenever the incident is updated. That second pass matters: severity and type are usually set at declaration, but the affected service often gets filled in later. A runbook scoped to a service attaches the moment that field is set.

Attachment only ever adds. Updating an incident never detaches a runbook that no longer matches, so a procedure that was relevant stays visible.

Every automatic attachment is recorded on the incident timeline with the rule that matched, for example “Matched Severity is one of Critical, Major”, so a responder can see why a procedure appeared. A runbook attached by hand records who attached it instead.

A runbook with no conditions attaches to nothing on its own. If you want one on every incident, turn on Attach to every incident and the Conditions column says so. Leaving both off is a valid choice: the runbook waits until someone attaches it by hand.

Attaching one by hand

Not every procedure is worth a condition. Three ways to pull one in when you need it:

• /ff runbook in the incident channel, or Attach runbook in /ff home, which opens a picker of everything not already attached
• The Runbooks panel on the incident page in the dashboard
• The attach_runbook MCP tool, so an agent can bring in the procedure it thinks applies

All three post the runbook in the incident channel exactly as an automatic attachment does. Attaching one twice does nothing the second time.

In the incident channel

When a runbook attaches, Firefight posts a message in the incident channel listing every step, and that message is the checklist you work from. Each step carries an I can take this button. Press it and the step becomes an action item assigned to you, and the row turns into Mark as done. Press that and the row is struck through with your name on it.

The message updates in place, so a runbook never fills the channel with posts no matter how many steps it has. Nothing is created until someone takes a step, which means the incident’s action list reflects the work people actually did rather than every step in the procedure.

View runbook opens the full procedure: every step with its complete instructions, plus a person picker on each one. That is where an incident lead hands work out. Assigning a step to someone creates or moves its action and posts it in the channel naming them, with the controls to work it, so they never have to come back to the runbook message.

Each completed step posts a short line naming the runbook it came from, so progress through a procedure is visible without scrolling back.

runbook.attached is recorded on the incident timeline when a runbook attaches, and each step you take records the usual action.created, action.reassigned, and action.completed events. All are available as outbound webhook events.

For AI agents and the API

Runbooks are first-class context for AI. Attached runbooks are included in the incident context that Firefight’s own incident responder sees, and any external agent connected over MCP can browse them with two read-only tools: search_runbooks to scan names and summaries, and get_runbook to pull the full procedure and steps.

The REST API covers the same ground at /api/v1/runbooks, addressable by ID or slug, under the runbooks permission resource. It reads with GET and writes with POST, PATCH and DELETE, and the upsert_runbook MCP tool does the same over MCP. Steps and conditions are only touched when you send them, so changing a summary never silently clears the procedure. Deleting is refused while a runbook is attached to an incident, and the refusal says how many.

Writing runbooks that work

A few habits make runbooks dramatically more useful, for humans and agents alike:

• Lead with symptoms. The first thing a responder needs to confirm is “is this what is actually happening?”
• Make each step a single imperative action, not a paragraph. “Check replication lag on the standby” beats a wall of prose
• Include the exact queries, dashboard links, and commands. Every lookup a responder has to improvise costs minutes
• Keep the summary honest and specific. It is how the right runbook gets found, by people scanning a list and by agents choosing what to read
• Review after every incident that used the runbook. Stale procedures are worse than none