Runbooks

Run reviewed, versioned operational procedures, including the ones that require an approval before they start.

What a runbook is

A named, versioned sequence of steps - the procedure that otherwise lives in a wiki page last edited eighteen months ago by someone who has since left.

Putting it in Shortspan buys three things: it is versioned, so you can see what changed and roll back; it can require approval before it runs; and every execution is recorded with who ran it and how it ended.

A runbook runs in one of two places. A local runbook runs on the machine running the CLI, as you. An SSH target runbook runs on that server, each step as sudo -n -u <run-as> -- <step>, held to the target's allow-list - see the runner policy.

What a step can be

One line is one step, and a step is one program with its arguments. It is split into words and executed directly - not handed to a shell - so shell habits do not carry over:

Instead of	Write
`cd /var/www/app` then `git pull`	`/usr/bin/git -C /var/www/app pull`
`php artisan migrate --force`	`/usr/bin/php /var/www/app/artisan migrate --force`
`npm run build`	`/usr/bin/npm --prefix /var/www/app run build`
`NODE_OPTIONS=… npm run build`	A script that sets the variable, allowed on its own
`a && b`, `a \| b`, `a > file`	Separate steps, or a script

Each step also starts fresh, so nothing carries between steps - not a directory, not a variable. Saving a runbook explains every line that cannot run and what to write instead. For anything more than a few commands, a script is simpler: allow /usr/local/bin/deploy.sh and make it the runbook's only step.

Running one

bash

shortspan runbook list
shortspan runbook show deploy-api
shortspan runbook check deploy-api
shortspan runbook run deploy-api

check runs everything shortspan ssh check does against the runbook's target, then looks at each step without running it: that the sudo rule allows that exact command, that the run-as account can reach the paths it names, and - for git, artisan, and npm steps - that the repository, application, or package works as that account. For a git pull it runs git ls-remote, which proves the account's deploy key and known hosts without fetching anything.

show prints the steps without running anything. Read it first - especially one you did not write, and especially one you have not run since it last changed.

run executes the steps in order, reporting each as it goes, and stops at the first failure. Completion is reported back with each step's status, exit code, duration, and the tail of what it printed, so the execution record in the console shows what actually happened. That output is redacted on your machine and again before it is stored.

Runbook steps can reference secrets and registered targets, which are brokered at the moment the step runs and audited individually. A runbook is not a way to get a credential you could not otherwise have.

Runbooks that need approval

An admin can mark a runbook as requiring approval. Executing it then creates a pending execution instead of running:

text

→ deploy-api requires approval before it can run.
  Requested. Approvers have been notified.
  Execution: 4f9c2a71-...

Project approvers are notified by email. Once one of them approves in the console, the execution can proceed. The approval names a specific execution, not the runbook - approving one run does not approve the next.

Authoring and versioning

Runbooks are written in the console under Runbooks. Each save creates a version with a snapshot of the whole document, so history survives even if the current version is edited beyond recognition. On Pro and above you can compare versions and roll back.

A rollback creates a new version equal to the old one rather than deleting anything. The history is append-only, so "we reverted the deploy runbook on the 14th" stays visible.

See Runbooks and approvals for the authoring interface.

Something here wrong or missing? Tell us.