Operations runbooks usually break in one of three ways:
- 📄 Stale documentation: wiki pages decay fast and become dangerous during incidents
- 🧩 Unreadable automation: scripts execute, but they do not explain intent, approvals, or rollback
- 🔒 Vendor lock-in: proprietary tools hide procedures outside Git, PR review, and CI
That leads to real pain:
- ⏱️ Slower incident response because procedures are outdated or missing
- 🧠 More tribal knowledge because new engineers cannot self-serve
- 🔁 Repeat incidents because fixes are never codified into the workflow
- 🧾 Weak audit trails for compliance-heavy operational work
- 🛠️ Duplicate maintenance across docs, scripts, and internal playbooks
- 🌱 GitOps maturity: infrastructure is already managed as code, but runbooks often are not
- 🚨 Incident tooling maturity: incident platforms improved, but the actual procedures still live in wikis
- 🏛️ Compliance pressure: SOC 2, ISO 27001, and DORA increasingly expect auditable operational workflows
- 🤖 AI readiness: structured, executable runbooks are a strong foundation for AI-assisted operations
Documentation and automation are the same file. When you update the command, you update the explanation in the same commit. They can never drift apart.
A .runbook file is extended Markdown with typed, fenced code blocks. The frontmatter defines
metadata, permissions, and approval rules. The Markdown body is the documentation. Specially-typed
code blocks (check, step, rollback, wait) are the executable units.
This means a single file is the document a human reads during an incident and the executable procedure the system runs. It lives in your Git repo, is reviewed in PRs, and is tested in CI.
- 📘 A human-readable document that explains what, why, and how
- ⚙️ An executable program with typed steps, checks, waits, rollback logic, and environment awareness
- 🌿 A version-controlled artifact that lives alongside your code and evolves with it
The repository ships with a self-contained example in examples/getting-started/demo.runbook.
It runs with standard Unix tools only, so you can try it without Docker, Kubernetes, or cloud credentials.
---
name: Getting Started Demo
version: 1.0.0
environments: [staging, production]
timeout: 5m
---
# Getting Started Demo
This runbook simulates deploying **{{runbook_name}}** version
**{{runbook_version}}** to **{{env}}**.
```check name="tmp-writable"
test -w /tmp
echo "/tmp is writable"
```
```step name="deploy-version" depends_on="apply-migration" rollback="rollback-version"
timeout: 30s
confirm: production
kill_grace: 5s
---
./scripts/deploy-version.sh "{{run_id}}" "{{runbook_version}}"
```
```wait name="health-soak" duration="15s"
abort_if: error_rate > 0%
---
./scripts/health-soak.sh "{{run_id}}" "{{runbook_version}}"
```Try it locally:
# From the repo root
make build
# Run the self-contained demo
./bin/runbook run examples/getting-started/demo.runbook --env staging
# Preview the execution plan without running anything
./bin/runbook dry-run examples/getting-started/demo.runbook --env stagingWhat this example demonstrates:
- ✅
checkblocks for prerequisites - 🪜
stepblocks withdepends_on - ♻️
rollbackhandlers for safe failure recovery - ⏳
waitblocks with health polling - 🛡️
confirm: productiongates for sensitive actions - 🌐
envfilters and built-in template variables
brew install runbookdev/tap/runbookPre-built binaries are published on every GitHub release for Linux (amd64, arm64), macOS (amd64, arm64), and Windows (amd64).
# Detect platform and download the latest release
VERSION=$(curl -s https://api.github.com/repos/runbookdev/runbook/releases/latest | grep tag_name | cut -d '"' -f4)
OS=$(uname -s | tr A-Z a-z)
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -sL "https://github.com/runbookdev/runbook/releases/download/${VERSION}/runbook_${VERSION#v}_${OS}_${ARCH}.tar.gz" | tar xz
sudo mv runbook /usr/local/bin/# Download the latest release
$VERSION = (Invoke-RestMethod https://api.github.com/repos/runbookdev/runbook/releases/latest).tag_name
$URL = "https://github.com/runbookdev/runbook/releases/download/$VERSION/runbook_$($VERSION.TrimStart('v'))_windows_amd64.zip"
Invoke-WebRequest -Uri $URL -OutFile runbook.zip
Expand-Archive runbook.zip -DestinationPath "$env:LOCALAPPDATA\runbook"
# Add to PATH (current session)
$env:PATH += ";$env:LOCALAPPDATA\runbook"Tip: Add
$env:LOCALAPPDATA\runbookto your system PATH for permanent access.
Every release includes a checksums.txt file (SHA-256). After downloading, verify the archive integrity:
sha256sum --check checksums.txt --ignore-missingRequires Go 1.26+ and a C compiler (CGO is needed for the embedded SQLite audit log).
git clone https://github.com/runbookdev/runbook.git
cd runbook
make build
sudo mv bin/runbook /usr/local/bin/# Scaffold from a template
runbook init --template=deploy my-deploy.runbook
# Preview (nothing runs)
runbook dry-run my-deploy.runbook --env staging
# Execute
runbook run my-deploy.runbook --env staging --var service=api --var version=2.4.0
# Review the audit log
runbook historyFull documentation is in the docs folder:
| Getting started | Install, scaffold, and run your first runbook |
| File format | Frontmatter, block types, and syntax reference |
| CLI reference | All commands, flags, and exit codes |
| Shell integration | Tab completion, rb alias, runbook-detect, and prompt indicator |
| Project detection | How project types, environments, and tool availability are detected |
| Template variables | {{variable}} resolution and built-ins |
| Safety features | Rollback, timeouts, confirmation gates, signal handling |
| Security | Static analysis, secret redaction, secure temp files |
| Audit logging | Execution history and runbook history |
| Configuration | ~/.runbook/config.yaml |
| Built-in templates | 10 production-ready starting points |
examples/getting-started- self-contained demo with checks, waits, rollbacks, and confirmation gatesexamples/docker-compose-deploy- realistic Docker Compose deployment flow for a VPS or bare-metal host
See CONTRIBUTING.md. Bug reports, feature discussions, and documentation PRs are all welcome.
Apache 2.0 — see LICENSE for details.