Skip to main content

Runbooks

An alert tells the on-call person what broke. A runbook tells them what to do about it. In Wakora a runbook is a piece of text attached to an alert rule, and it travels with the incident: it is on the incident row in the console, in the Telegram and push messages, in the e-mail, on the Slack and Teams cards, in the webhook payload, in the Jira issue, and in the API and MCP answers. The person woken at three in the morning gets the instruction in the same message as the alert.

Runbooks come with the Pro plan and above. On a lower plan the ones you wrote stay stored, but nothing shows them.

Writing a runbook​

Alerting, Rules. Every rule row carries a runbook card: add runbook opens the editor.

  • Title: the short label that appears in notifications ("Disk full on a web node").
  • Text: the instruction itself, up to 20000 characters. Plain text; line breaks and indentation are kept, so a numbered list of commands reads as you typed it.
  • URL (optional): a link to the longer page in your own wiki. The title in a notification links there when it is set.
  • Scope: the whole workspace, hosts carrying a tag, or one host. One rule can have several runbooks with different scopes: a general "disk is filling up" for everyone and a specific one for the database hosts.
  • Object pattern (optional): a wildcard over the incident's object, the thing the rule fired on (a mount like /var/lib/mysql, a site, a service name, a container image). * matches anything, so /srv/* covers every mount under /srv.

A rule with runbooks shows a small badge in the rules list; the card under the rule lists each one with its scope, and add a narrower runbook adds the next.

Which runbook the incident gets​

When an incident opens, the runbooks of its rule are matched against the host and the object, and the most specific ones win: a runbook for that host beats one for a tag the host carries, which beats the workspace one; on the same level, a runbook whose object pattern matched beats one without a pattern. Everything that shares the winning level is shown, so a host carrying two tags that each have their own runbook gets both.

The match is made when the incident is displayed or delivered, not frozen at birth. Edit a runbook and the next notification, and the incident row the moment you reload it, carry the new text. The one exception is Jira: the issue created from an incident takes a snapshot of the runbook at creation time, because a ticket is a record.

Where it shows up​

  • Console: the expanded incident carries a runbook card next to the timeline.
  • Telegram, push, e-mail: the digest line of the incident ends with the runbook title; with several, the first title and a count. The title links to the URL you set, or to the incident in the console.
  • Slack and Teams: the card carries the runbooks.
  • Webhook: each incident in the payload carries a runbooks array (title, url, text, and matched, the scope that selected it). See Webhooks.
  • Jira: the issue description carries the runbook text (snapshot at creation).
  • API and MCP: GET /incidents/{num} and the get_incident tool return the runbooks that apply, so an AI assistant reading an incident reads your instruction with it.

Who can edit​

Runbooks are a separate capability in the role matrix (Settings, Team): owners, admins and responders can write them by default; viewers and billing cannot. The same capability gates the API: a token writes runbooks only when its owner's role allows it, and a workspace token without a person behind it needs the admin scope.

API​

MethodRouteScopeWhat it does
GET/runbooksreadEvery runbook of the workspace.
POST/runbooksactCreate: rule, scope (all, tag or host), value (the tag, or the host uuid), pattern, title, url, content.
POST/runbooks/{id}actUpdate; fields you leave out keep their value.
DELETE/runbooks/{id}actDelete.

Writes need the act scope plus the runbooks capability of the token owner. Details and the token model: API overview.