Skip to content

Runbooks

Operational procedures for the day-to-day and infrequent-but-important tasks. Each runbook is self-contained — you should be able to execute it without reading anything else first.

Day-to-day

  • Recover from drift — when $HOME falls out of sync with the source state and mac flags it.
  • Brew sync — merging interactive brew install/uninstall events back into Brewfile.tmpl so they survive the next bootstrap.

Infrequent

  • New machine bootstrap — taking a clean macOS install to fully configured. End-to-end procedure.
  • Secret rotation — rotating a single secret (AWS key, GitHub PAT) or the age key itself. Includes "Back up the age key" strategies.
  • Branch protection — the 12 required CI checks on main, how to recreate the protection rules if they're disabled, and how to add new required checks.

When to write a new runbook

A new runbook is warranted when:

  • The procedure has more than three steps and is infrequent enough that you'll forget it between runs.
  • The procedure has a safety-critical step (secret handling, destructive chezmoi action) that benefits from a checklist.
  • An operational pattern recurs across multiple machines (new bootstrap, drift recovery) and you want one canonical source.

For everything else, an ADR or a comment in the code is usually the right home.