Skip to main content
A runbook is a written procedure for fixing a known problem, such as “restart the checkout pods” or “fail over the database”. When you connect your runbooks to Resolve, CloudThinker reads them during a root cause analysis (RCA) and proposes the matching fix instead of improvising one.
Legacy. Runbooks carries a Legacy label beside its name in the sidebar and at the top of the page. It works as described here, and no replacement or removal date has been announced. Connected sources stay in Confluence, GitHub or GitLab, so your procedures stay usable whatever happens to this page. If you’re deciding how much to invest in it, ask support@cloudthinker.io.

​
How it works

  1. You add a runbook source: a Confluence space, a GitHub or GitLab repository, or Markdown files you upload.
  2. During root cause analysis, CloudThinker searches your enabled sources for a procedure that fits the problem it found.
  3. If the procedure includes commands that change something, each change goes through your workspace’s Approvals, like any agent write. When a person has to decide, the run stops at Action requires approval. The banner shows in the incident’s analysis on Resolve → Investigation, below the assessment.
  4. Every attempt is recorded on the Execution history tab with its policy decision, approval, and outcome.
Every change an agent makes goes through your workspace’s Approvals first. On the default Auto · Rules + AI · Ask me mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on Rule enforcement for your workspace. Choose Manual to approve every change yourself. Read-only commands (ones that only look, like kubectl get pods) never wait for a runbook approval, from an upload or a connected source. Commands that change infrastructure, like kubectl rollout restart, go through Approvals. Control command effects explains how a runbook’s own effects fit in.

​
How CloudThinker finds a runbook

CloudThinker searches each enabled source with a description of the problem it found: CloudThinker gathers the candidates from every enabled source, then reads the best match before it plans the fix. So write runbooks the way your alerts read. Put the symptom and the service name in the title and first lines, for example # checkout-api pods in CrashLoopBackOff, not # Procedure 7. For uploads, those first lines are most of what CloudThinker sees when it chooses. Use one procedure per page or file.

​
Where commands run

A runbook command runs like any other agent command, through the connection for the target system and with that connection’s credential and permissions. The credential sets the scope. A read-only credential can’t write, whatever the runbook says, and a connection with Allow writes off refuses writes too. Every write also goes through Approvals, including its list of calls that never run. For the machine the command runs on, see Where agents run.

​
Prerequisites

  • The workspace Admin role to add, edit, publish, or delete sources. Developers and Viewers can see sources and Execution history. See Roles.
  • Approvers for runbook actions follow your Approvals setup, not the Admin role. See approvers.
  • For Confluence, GitHub, or GitLab: a working connection that can read the runbooks. The source form can’t be saved without one.
  • For uploads: your procedures as .md files, with commands in fenced code blocks.

​
Choose a source type

Connected sources stay in their own system. CloudThinker reads them at RCA time, so an edit in Confluence or a merged change in Git is picked up on the next investigation without a re-sync. Before you add a source, check that a runbook source is the right home for the procedure: Teach CloudThinker compares runbook sources with skills and knowledge bases.

​
Connect a Confluence, GitHub, or GitLab source

1

Open Runbooks

In the sidebar, open Resolve → Runbooks (under Configuration). The page has two tabs: Runbook sources and Execution history. If you have no sources yet, the page lists each source type: a connected one shows the connection name, an unconnected one shows Connect first.
2

Add the source

Click Add source (or the source type in the empty state). In Add Runbook Source, enter a Source Name, for example SRE Runbooks, pick the Source Type, and select the connection.
3

Narrow what CloudThinker searches

For Confluence, set a Confluence Space Key such as SRE and any Labels. For GitHub or GitLab, pick the Repository, then optionally a Branch, a Path Prefix such as docs/runbooks, and File Patterns such as *.md. Click Add Source.
Success state: the source appears in the list with its type and scope, for example GitHub · acme/runbooks · docs/runbooks, and its toggle is on. CloudThinker doesn’t extract or sort commands from a connected page the way it does for uploads. The form’s notice says every command from the source requires approval. In practice that means every change-making command: read-only commands run without a runbook approval, and changes go through your workspace’s Approvals. There’s no per-command effect to set for these sources.

​
Upload Markdown runbooks

1

Open the upload dialog

On Resolve → Runbooks, click Upload runbook (or Upload a runbook in the empty state).
2

Add your files

Drag in up to 20 .md files, up to 5 MB each. Each file gets a Runbook name, which you can edit before uploading.
3

Upload

Click Upload. Each file shows Uploading… and then Extracting commands… while CloudThinker pulls the commands out of its code blocks.
Success state: each file appears as its own source in the list, published and searchable right away. Uploads are never created as drafts. Click the book icon on its row to open a read-only preview, with a Download button for the original Markdown. A runbook written like this gives CloudThinker clear, separable commands:
From this file, CloudThinker records kubectl rollout restart as a change-making command that requires approval. The two read-only commands aren’t recorded, and CloudThinker can run them during RCA without a runbook approval. At upload, an AI model called by CloudThinker’s backend reads the fenced code blocks and keeps only the commands that change something. A pipeline counts as change-making if any part of it writes. Each kept command must appear in a code block, so nothing is recorded from prose. If the model step fails, a fixed list of look-only commands (such as kubectl get, kubectl logs, cat, and grep) decides instead, and anything not on that list counts as change-making. For where model calls go, see Data CloudThinker handles. A misclassified command can’t skip approval. A write the model missed still runs through the connection’s credential and Allow writes setting, and through Approvals, like any agent write (see Where commands run). Where your workspace shows Policies, you can review the recorded commands, see Control command effects. To change an uploaded runbook, delete its source and upload the new version. There’s no in-place edit for uploads. Old Execution history rows keep the runbook’s title, but they’re no longer tied to the deleted source.
The new upload gets a new policy, so every command starts again at Require Approval. Any Allow or Deny you set on the old upload is gone.

​
Control command effects

An effect is a runbook’s own rule for a change-making command. Your workspace’s Approvals mode applies to every change as well. Where Policies is off, which is most deployments, effects aren’t applied and Approvals alone decides: on the default Auto · Rules + AI · Ask me mode, AI judgment can let a change run without asking, and an Allow Rule can too once CloudThinker turns on Rule enforcement for your workspace. To make every runbook change wait for a person, choose Manual. Which effects you can get depends on the source type: Each upload gets its own policy named Manual Runbook: <runbook name>, with one statement per extracted command. The Policies section on Resolve → Settings is off in most deployments. Where it’s on, you can open that policy there and change a command’s effect, for example to Allow for a safe restart you run often. Without it, every command keeps Require Approval on its policy, and your Approvals mode decides whether a change waits. To ask whether it can be turned on for your deployment, email support@cloudthinker.io.

​
Approve a runbook action

When CloudThinker wants to run a change-making command during an incident, the incident’s analysis shows an Action requires approval banner with the runbook it came from.
1

Open the conversation

On the incident, click Go to conversation.
2

Decide

Read the proposed command on the approval card and click Approve or Decline. Approving lets the run continue. Declining stops that action. The card has no field for editing the command: to run something different, decline and say what you want in the conversation.
Success state: the banner disappears, and the execution shows Approved on the Execution history tab. A declined action shows as Rejected there. The run waits at that step until someone decides. Who can approve follows your workspace’s approval setup, see approvers. If you can’t approve, the card says it’s waiting for an approver. The person who started the conversation also sees a Notify approvers button on it. To get approval requests by email or chat, turn on Agent approvals in Notifications.

​
Review what ran

Open the Execution history tab on Resolve → Runbooks. Each row is one runbook action: Check Status before you close an incident. Approved means a person said yes. Only Completed means the command ran. For trends across incidents, open the Runbook analytics tab in Resolve Insights.

​
Manage sources

Hover a source row to see its actions:

​
Troubleshooting

The source form needs a connection for that platform. Click the row to connect it, or add it from Connections, then come back and click Add source.
Check that the source’s toggle is on and that it isn’t marked Draft. Then check the scope: a wrong Confluence Space Key, Path Prefix, or File Patterns value hides the file. Give the runbook a title that names the symptom and service, see How CloudThinker finds a runbook.
Only .md files up to 5 MB are accepted, and at most 20 per upload. Split a large runbook into one file per procedure.
Commands must sit in fenced code blocks. Commands in plain paragraphs, or read-only commands only, produce nothing to approve.
A runbook action is pending. Open the incident, click Go to conversation, and click Approve or Decline.

​
Next steps

See how RCA uses runbooks

Follow an investigation from evidence to proposed fix.

Set up approvals

Decide who approves change-making actions and how.