Runbooks

A runbook is your team’s answer to “we’ve seen this before, here’s what to do.” In Firefight a runbook is more than a wiki page. It has 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 Configure → Runbooks. Admins manage them, and so does a member an admin granted runbooks under Permissions.

A runbook can also do work for you, and how depends on whether your workspace has Workflows, the Workflows page under Halon in the sidebar.

• Without Workflows, a step can name the tool Halon runs it with, and Halon runs the whole runbook when you ask for it by name. See Runbooks Halon can run.
• With Workflows, a runbook links one workflow, and Run it starts that workflow. Its steps name no tools. See Running a runbook with a workflow.

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
Other names	Optional. What people call the procedure besides its name, like “release firefight” or “ship it”
Tool on a step	Optional, without Workflows. The tool Halon runs the step with, and the arguments it passes. A step with a tool is one Halon can run for you
Inputs	Optional, without Workflows. What Halon asks each time it runs the runbook, each with a question and a default, like which version bump with patch as the default
Watch afterwards	Optional, without Workflows. What Halon follows once every step went through, like a release run and the deploy after it, reporting back as it goes
Workflow	Optional, with Workflows. The one workflow Run it starts

Content and steps play different roles. Content is the narrative, with context, decision points, queries to run and 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.

Conditions are evaluated when an incident is declared, and again whenever the incident is updated. That second pass matters, because 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 then 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, with every step’s complete instructions and 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.

When the runbook has an external URL, Open runbook on the message opens it.

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.

Runbooks Halon can run

This section applies to a workspace without Workflows.

Some procedures are the same handful of calls every time, like starting a release, waiting for its run to finish and then following the build and deploy. Save one as a runbook and you can ask Halon for it by name, such as “release Firefight”, and it runs the steps for you.

Saving one from a chat. After Halon does a multi-step task with you, say “remember this as Release Firefight”. Halon saves a runbook whose steps are the calls it made, turns anything you chose this time (a version bump, say) into an input with your choice as the default, and keeps what it watched afterwards. When you have it do the same multi-step task again, Halon offers to save it.

Writing one yourself. Add or edit a runbook under Configure → Runbooks. For each step, pick the tool Halon runs it with from the list, where Firefight’s own tools are grouped by what they work on and each connection’s tools sit under its name, and fill in the fields that tool takes. Required fields are marked. The Run by Halon part of the dialog holds its other names, its inputs, and Watch afterwards, where you choose what to follow and what counts as done, with an optional time limit. What to follow is a check on a resource from the map, such as Run history or Status, or any read tool Halon can use in a chat, with a field for each thing that tool takes, such as following the newest run of a release workflow through the provider’s API. For a read tool you can also name the part of a long answer to watch, such as data.status. Each thing to watch can have a name, and without one it is named after what it checks, such as Run history or Status. When something is missing, the dialog names the item, such as “Watch ‘Deploy finished’: needs the capability to check and the resource, or a read tool”, or “Watch 2” for one with no name. Leave the time limit empty and Halon learns it from how long these usually take. A field can take an input instead of a fixed value, written as {{bump}} or picked from the list. Anything Halon saved that the dialog has no field for is listed under the step and kept as it is.

Running one. Ask for it by name or by one of its other names. Halon finds it, says what it will do, and asks for any input that has no default. Nothing runs until you confirm. The confirmation lists every step with the exact tool and arguments it will use, with your inputs filled in, and what it will watch afterwards, so you confirm the run itself rather than Halon’s description of it.

Each step runs as you, with your permissions. A step that changes something still needs the grant or permission pack it always needs, and an approval rule that covers it still applies. The run stops at the first step that is refused, that waits for an approval, or that fails, and Halon tells you which step and why. Nothing after that step runs. When every step went through, Halon starts watching what the runbook says to follow and reports back in the chat, in its Slack thread and in a direct message to you, as it does for any watch.

A runbook with no tool on any step is an ordinary incident runbook. It attaches, posts its checklist and hands out steps exactly as described above, and Halon never runs it.

Running a runbook with a workflow

This section applies to a workspace with Workflows. A runbook links one workflow, and Run it starts that workflow. The runbook stays the guide people read and work through, and the workflow does the part Firefight runs for you, such as starting a release and watching it go out.

To link one, edit the runbook under Configure → Runbooks and pick it under Workflow. The link below it opens the workflow on its own page, where you change what it does. Pick None, people follow it by hand to unlink it. Other names sit beside it, so people and Halon can ask for the runbook by the name they use, such as “ship it”.

Run it appears in four places:

Where	How
The runbook’s page	Open the runbook under Configure → Runbooks
An incident in the dashboard	Next to the runbook in the Runbooks panel
The incident channel	On the runbook’s message, and in View runbook
A chat with Halon	Ask for it by its name or another name, such as “release Firefight”

Before it starts, Run it asks each question the workflow asks, filled in with its default. The run acts as the workflow itself, with only what an admin granted it, never as the person who pressed the button. A message confirms it is running with Follow its run, and a run started in an incident names that incident. In a chat, Halon shows the workflow’s steps and your answers on a card, and starts it once you confirm.

A workflow that is a draft or switched off cannot run. On the dashboard Run it is greyed out and hovering it says why. In Slack, pressing it says why it did not start. An admin publishes the workflow from its page first.

When Workflows is switched on for your workspace, each runbook that named tools, inputs or a watch gets a workflow of its own made from them, named after the runbook and left as a draft to publish. The runbook links it and keeps every step as its checklist.

When a runbook names a tool for a step, an input or something to watch, through the API or the upsert_runbook MCP tool, those go into its workflow and the step stays on the runbook’s checklist. A runbook that links no workflow is made one, as a draft. Over MCP it is published when you may publish it, otherwise the admins are asked. A step that changes something also needs to say how to undo it, in undo, before its workflow can be published.

For AI agents and the API

Runbooks are first-class context for AI. Halon can find and read runbooks, attach one to an incident and claim its steps when you ask it to, and any external agent connected over MCP can browse them with two read-only tools. search_runbooks scans names, summaries and other names, and get_runbook pulls the full procedure and steps. An agent that wants a saved runbook run asks Halon for it with ask_halon, and the run waits until you confirm it in Firefight.

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. A step also takes tool and arguments, and a runbook takes inputs, aliases and watch, each changed only when you send it. 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