Runbooks

Overview

A Runbook is a numbered, time-bounded sequence of steps that a human (or a future automation) follows to execute a known procedure — restart a service, rotate a certificate, restore a database, validate a deploy. Runbooks live under /ws/{slug}/runbooks and are the workspace's institutional memory: the thing you copy from when starting a change, and the thing you link from when documenting an incident.

Each runbook has a title, summary, category, version, ownership, and an ordered list of RunbookStep rows. A step carries an instruction (markdown), expected outcome, time estimate, optional verification command, optional rollback note, and flags for requires_approval and is_destructive.

Why it exists

The most common cause of weekend incidents is the same procedure done two different ways by two different operators. Runbooks remove that ambiguity. They also remove the "where is that doc?" problem: every change can be authored from a runbook, and every incident can be remediated via a runbook, with the same numbered steps and the same checkpoints. The audit trail captures every execution, so an auditor sees who ran what, when, with what timing variance, and with what outcome.

Vigilo treats runbooks as first-class data, not Confluence pages. They have versioning, they have execution history, they have inline ownership, and they sync bidirectionally with change implementation plans.

Key concepts

• Runbook fields — title, key (RB-NNNNN, auto-incremented per workspace), description (markdown), category (free-text, used by filter chips), version (integer, bumps on every saved edit), owner (UserProfile), is_published (only published runbooks are pickable from the Change implementation-plan importer), archived_at (soft delete).
• RunbookStep fields — order (integer, 1-based), title, description (markdown), owner_role (which role is expected to run this step), est_minutes, verification (command or check the operator confirms), rollback_note, requires_approval (gates execution on a separate confirm dialog), is_destructive (renders the step with a danger badge).
• RunbookExecution — a row created when an operator opens a runbook in "execute" mode and presses Start. The execution snapshots the runbook version, records the operator, and links to an optional ChangeRequest or Incident. Each step run produces a RunbookStepEvent with started_at, completed_at, status (done, skipped, failed), and an optional note.
• Versioning — every save bumps version and writes a RunbookVersion row containing the prior body. The version history lives under the Runbook detail's History tab and supports a side-by-side diff.
• Change ↔ Runbook sync — when authoring a change, click Import runbook on the implementation plan to copy a runbook's steps into the change. When the change reaches completed, click Save as runbook to push the final step set back as a new runbook version. Both operations are non-destructive.

Common workflows

1. Author a runbook from scratch

1. Open Work → Runbooks → + New runbook.
2. Give it a title, category, owner, and a short description (markdown supported — paste links to dashboards, prerequisite docs, etc.).
3. Add steps one by one. For each, set est_minutes, the owner role, and any verification command. Toggle is_destructive for anything that can't be undone trivially.
4. Click Publish when the runbook is ready to be imported. Drafts remain visible to the owner but won't appear in importer dropdowns.

2. Execute a runbook end-to-end

1. Open the runbook detail and click Execute in the header.
2. Optionally link the execution to an open ChangeRequest or Incident — the link surfaces in the audit log on both sides.
3. Press Start. The first step expands; press Done when complete or Skip with a reason.
4. Steps with requires_approval open a confirm dialog before they can be marked done.
5. After the last step, the execution is sealed — no further edits. Timing variance (actual vs estimated minutes) appears on the execution summary.

3. Import a runbook into a change

1. Open the change detail and click Implementation plan.
2. Click Import runbook (icon in the plan footer). Pick a published runbook from the dropdown.
3. The runbook's steps are copied into the change as implementation tasks. The Implementation plan now shows a Source: RB-XXX (v3) banner at the top.
4. Edit the copied steps freely — they're now change-owned. If the source runbook ships a newer version, the banner shows a yellow chip; click Re-import to take the update or Clear source to dismiss.

4. Save a change's implementation plan back as a runbook

1. After the change reaches completed, open its Implementation plan tab.
2. Click Save as runbook in the plan footer.
3. Either create a new runbook (give it a title and category) or update an existing one (the dropdown lists every published runbook). Updating bumps the version.
4. The audit log records both the source change and the runbook target so the lineage is queryable.

5. Diff two versions of a runbook

1. Open the runbook detail → History tab.
2. Pick From and To versions (radio buttons). Click Compare.
3. The diff shows added/removed/changed steps with line-level markers. Useful for an auditor reviewing what changed between two procedure versions.

Permissions

Runbook endpoints inherit WorkspaceScopedMixin, so a workspace cannot see another workspace's runbooks.

Troubleshooting

The Import-runbook picker is empty. Only is_published runbooks appear. Open the runbook you want and click Publish.

A requires_approval step won't open the confirm dialog. The operator's role does not satisfy the step's owner_role. Either change the step's role or escalate to someone who has it. Roles are checked at click-time, not at execution-start.

Save-as-runbook is greyed out. Either the change isn't in completed yet, or every step in the plan is empty. Vigilo refuses to save a runbook with zero non-empty steps so that the resulting record is actually useful.

The runbook source banner disappeared after editing the change. The banner relies on the change carrying a non-null source_runbook_id. If a user clicks Clear source, the link is removed deliberately and the banner won't return until a new import.

Related articles

• Change requests — see the Implementation plan section for the Import / Save-as flow.
• Incidents — link an execution to an incident for the remediation audit trail.
• Change FSM — runbook execution can gate the start → in_progress transition.