Keep runbooks in Git
A repository folder can be the source of truth for a project’s runbooks. CI publishes the folder whenever the default branch changes, and pull requests get a check that changes nothing. It works with any Git host and needs no app installed.
Layout
Section titled “Layout”One folder per project, named by the project’s slug. Each runbook file sits
directly inside, and its metadata.id names the runbook:
Directoryrunbooks/
Directoryapp/
- rotate-api-keys.yaml
- post-deploy.yaml
Directorydata-pipelines/
- backfill-a-workspace.yaml
A repository with a single project can use one folder of *.yaml files
instead.
Publishing
Section titled “Publishing”runbook sync push runbooks --each-project # every project folderrunbook sync push runbooks/app --project app # one folderA push sends the whole folder in one request:
- All or nothing. Every file is compiled first. If any is invalid,
nothing is published, and the CLI lists each file’s errors with line
numbers (exit code
2). - Versions. A changed runbook gets a new version that records the commit
and branch. An unchanged one keeps its version (
unchanged). - New runbooks are created, and runbooks written in the app with the same
ID are taken over (
adopt). - Read-only in the app. A runbook published from Git can’t be edited in
the web app; the editor says so. Change it with a pull request, or choose
Edit here instead (
POST /v1/runbooks/{rb}/detach, needsrunbooks:publish). The next push of its file takes it back. - Removing a file does nothing unless you pass
--prune, which archives the runbook. Its versions and runs are kept, and a later push of the file brings it back. --dry-runvalidates and reports what would change, without changing anything. Use it on pull requests.
The commit and branch come from --commit and --branch; without them, the
CLI reads GITHUB_SHA and GITHUB_HEAD_REF / GITHUB_REF_NAME, then the
checked-out repository.
Starting from the app
Section titled “Starting from the app”To move runbooks you wrote in the app into a repository:
runbook sync pull runbooks --each-project # every project you can readrunbook sync pull runbooks/app --project apppull writes each runbook’s latest published version to <id>.yaml. It
skips runbooks that were never published and archived ones. Commit the files,
then let CI push them; the first push adopts each runbook.
Tokens
Section titled “Tokens”Sync needs runbooks:publish in each project. A service token acts for one
project, so create one per project with the editor role:
runbook token create --kind service --role editor --project app \ --scope runbooks:read --scope runbooks:publish --name "ci sync app"With --each-project, the CLI uses RUNBOOK_TOKEN_<PROJECT> for each
project when it’s set: the slug upper-cased, with - as _, so
data-pipelines uses RUNBOOK_TOKEN_DATA_PIPELINES. Otherwise it uses
RUNBOOK_TOKEN.
GitHub Actions
Section titled “GitHub Actions”-
Store each project’s token as a repository secret, and your server’s URL as the variable
RUNBOOK_HOST. -
Add the workflow:
.github/workflows/runbooks.yml name: Runbookson:pull_request:paths: ['runbooks/**']push:branches: [main]paths: ['runbooks/**']jobs:sync:runs-on: ubuntu-latestenv:RUNBOOK_HOST: ${{ vars.RUNBOOK_HOST }}RUNBOOK_TOKEN_APP: ${{ secrets.RUNBOOK_TOKEN_APP }}RUNBOOK_TOKEN_DATA_PIPELINES: ${{ secrets.RUNBOOK_TOKEN_DATA_PIPELINES }}steps:- uses: actions/checkout@v4# Install the runbook CLI here: a release binary, or the server# image, which includes it.- name: Check (pull request)if: github.event_name == 'pull_request'run: runbook sync push runbooks --each-project --dry-run- name: Publish (main)if: github.event_name == 'push'run: runbook sync push runbooks --each-project
The API behind it is POST /v1/projects/{p}/sync, in the API
explorer.