// the find
braintree/runbook
A framework for gradual system automation
Runbook is a Ruby DSL for writing ops procedures that double as both human-readable docs and executable scripts, built on SSHKit for remote command execution. It's aimed at SRE/ops teams who want to move a manual runbook toward automation gradually instead of rewriting it as a script in one shot.
The same definition renders to markdown for a human to follow or executes for real via SSH, so the doc and the automation can't drift apart the way a wiki page and a deploy script usually do. Execution state is saved at each step, so a failed run can resume where it left off instead of restarting from scratch. Noop mode lets you dry-run and see exactly what would execute before it touches anything. Tmux integration with named pane layouts is a nice touch for interactive incident response where you want logs, monitoring, and the runbook itself visible side by side.
Last commit is from August 2023 and it sits at 768 stars, so this is a quiet, low-adoption project you'd be betting on largely alone. It's Ruby/SSHKit-only, which is a hard sell if your infra isn't already Capistrano-adjacent. State passing between steps relies on instance variables synced through a 'repo', and the docs themselves warn these can silently clobber the DSL's own method names — an easy footgun in anything non-trivial. There's no built-in secrets handling; anything sensitive goes through plain env vars or your own ask/capture logic. The docs also admit the declarative model breaks down for real branching logic ('deep nesting' is explicitly discouraged), which caps how far you can push it before you're back to writing procedural Ruby anyway.