Docs Site
The public docs site at https://mrbro.dev/infra/ is built by .github/workflows/site.yaml from apps/docs. It renders ARCHITECTURE.md, STRUCTURE.md, each app’s AGENTS.md, docs/runbooks/, and docs/solutions/, plus Archify diagrams and a status page fed by the status-history artifact. This runbook covers enablement, history, recovery, takedown, and the redaction gate. Package internals are in apps/docs/AGENTS.md.
How it flows
Section titled “How it flows”Status Snapshot(status-snapshot.yaml) runs at minutes 11 and 41 of every hour. It is the only writer of thestatus-historyartifact.- When a snapshot run completes,
Sitestarts throughworkflow_run. It builds only if that run succeeded, ran onmain, and came fromscheduleorworkflow_dispatch. Sitedownloads the triggering run’s artifact, builds, runs the redaction gate twice, and deploysapps/docs/dist.- A push to
mainthat touches a rendered source orapps/docs/**, or a manual dispatch, locates the newest usable artifact withstatus history-locateand fails if there is none. - Qualifying publish runs (a push, a dispatch, or a
workflow_runfrom a successfulmainsnapshot) share one concurrency group, and a newer one cancels an older in-flight one, so an older build never deploys after a newer one. Aworkflow_runthat the build guard would skip gets its own group and cancels nothing. A cancelled deploy leaves the live site as it was. Each pull request has its own group. Never re-run a cancelledSiterun, because a newer run superseded it. A re-run joins the group as the newest request, cancels the newer publish, and deploys the older commit. To republish, dispatchSiteonmaininstead. - Pull requests build with the committed fixture and never download history, upload a Pages artifact, or deploy.
History lives only in the artifact (7-day retention, newest copy wins). The site never writes it.
One-time Pages enablement
Section titled “One-time Pages enablement”Marcus does this by hand. It is a repo setting, so the workflow cannot do it.
- Settings → Pages → Build and deployment → Source: GitHub Actions.
- Leave the custom domain empty.
mrbro.devcomes from the user site, and this project site is served under/infra/. - Make sure the
github-pagesenvironment allows deployments frommain. - Dispatch the workflow:
gh workflow run site.yaml --repo marcusrbrown/infra --ref main. - Verify
https://mrbro.dev/infra/serves the status page and a diagram. The next snapshot run should republish with one more sample.
Order matters: bootstrap the history first (below), then enable Pages, then dispatch Site. Before bootstrap, a main build fails on purpose.
Bootstrap
Section titled “Bootstrap”Scheduled snapshots never create history. To create the first artifact:
gh workflow run status-snapshot.yaml --repo marcusrbrown/infra --ref main -f bootstrap=trueThe run refuses if a valid history already exists, and refuses off main. Verify two samples per app after the next scheduled run.
Expired or corrupt history
Section titled “Expired or corrupt history”Snapshots stop for more than 7 days, or an invariant failure leaves a corrupt artifact: the history is gone or unreadable. Recovery accepts a history reset; the 90-day view starts over.
-
List the artifacts:
Terminal window gh api 'repos/marcusrbrown/infra/actions/artifacts?name=status-history&per_page=100' --jq '.artifacts[] | [.id, .created_at, .expired] | @tsv' -
Delete every
status-historyartifact:Terminal window gh api 'repos/marcusrbrown/infra/actions/artifacts?name=status-history&per_page=100' --jq '.artifacts[].id' \| xargs -I{} gh api -X DELETE repos/marcusrbrown/infra/actions/artifacts/{} -
Bootstrap again (see above).
A lookup error is not the same as an empty history: the lookup exits non-zero on API errors, so an outage never triggers a reset. Retry the failed run before deleting anything.
Emergency takedown
Section titled “Emergency takedown”In this order, so nothing republishes while you unpublish:
-
Disable both workflows:
Terminal window gh workflow disable "Status Snapshot" --repo marcusrbrown/infragh workflow disable Site --repo marcusrbrown/infra -
Unpublish Pages:
Terminal window gh api -X DELETE repos/marcusrbrown/infra/pagesRe-enabling later repeats the one-time enablement.
-
Optionally delete the remaining
status-historyartifacts (see the delete command above).
Anything already fetched or indexed stays out of reach. If a secret leaked, rotate it first; takedown does not undo exposure.
Redaction gate
Section titled “Redaction gate”The gate runs on the source markdown and again on apps/docs/dist. A failure blocks the deploy.
Allowlisting a hostname
Section titled “Allowlisting a hostname”A real hostname the docs need goes into apps/docs/redaction/hostname-allowlist.json in the same PR that adds it. Each entry carries:
host: the hostname.reason: why it is public and needed.scope: the file classes it applies to, such as**/*.mdor**/*.html.
Keep the scope narrow. Third-party runtime URLs in Archify HTML or Starlight bundles get a scoped entry, never a global one. A pattern-level exemption is not allowed.
Fixing a gate failure
Section titled “Fixing a gate failure”Reword the source. Hostname and IP findings print the value, file and line. A false positive (a non-hostname or non-IP that matched) is fixed by rewording, not by exempting it. Secret findings print the pattern ID only, never the match; find it in the file and line, remove it, and rotate the credential if it was real.
Schedule auto-disable
Section titled “Schedule auto-disable”GitHub disables scheduled workflows after 60 days without repo activity. If the daily report’s snapshot-age row goes stale and no run appears, re-enable both:
gh workflow enable "Status Snapshot" --repo marcusrbrown/infragh workflow enable Site --repo marcusrbrown/infraIf snapshots were off for more than 7 days, the history has expired; follow the reset path above.
Gap threshold
Section titled “Gap threshold”A gap is a spacing between samples of more than 75 minutes (GAP_THRESHOLD_MS in apps/docs/src/lib/history-view.ts). The cron runs every 30 minutes, but scheduled runs start late. Over the first week no run was skipped, yet the daily 00:11Z run landed up to 56 minutes after the one before. In that period a gap would have meant a missed run, though a longer delay can still produce one. The coverage count (“N of M samples”) is approximate and can hide a single missed slot. Gaps are shown, never interpolated. The end-to-end probe has its own 45-minute staleness limit (PROBE_STALE_MS), because the monitor runs every 15 minutes.
To re-measure before changing the threshold, download the newest status-history artifact and compute the spacing between consecutive t values in any apps/<app>.json. Re-measure after a cron change, or when a late run approaches the threshold. The measured distribution is in Size the gap threshold from measured run intervals.