Engineering runbooks

owner Stefan Coetzeecreated 2026-10-11updated 2026-10-11reviewed 2026-10-09review by 2027-01-071 min readreference

Each runbook covers one failure that has happened, with how to see it, the cause and the fix. Observability runbooks (Loki, Grafana) are in the Observability space.

Symptom	Runbook
The deploy job did not run; the conformity job is red	Gate blocked a deploy
`git push` is rejected after a successful run	Push rejected after a deploy
`site.consistency` fails with a relative link that is not in the page text	Link check flags a template string
A deploy passed the gate but a live page is wrong	Roll back a deploy

Child pages

Gate blocked a deployThe conformity job failed, so the deploy did not run and the previous build is still live; find the failing check, fix the page, push again.
Push rejectedA push to main is rejected because changes reach main through pull requests; open a pull request. A push to your branch is rejected after a rebase; push it with --force-with-lease.
Link check flags a template stringThe gate reads every href in the page source, including ones inside JavaScript template strings; build such links with a.href in code.
Roll back a deployA deploy passed the gate and the live site is wrong; revert the commits on main and push, so the workflow gates and deploys the earlier state. Re-running an older run does not roll back.

Built from scripts/docs by build_docs.py.