From c2e69965b5f085869f5f8bfa01835d6c1c4cdd7f Mon Sep 17 00:00:00 2001 From: operations <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 03:07:16 -0500 Subject: [PATCH 1/2] docs(runbooks): list every availability probe and the software-factory failure mode Signed-off-by: operations <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- runbooks/availability-failure.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/runbooks/availability-failure.md b/runbooks/availability-failure.md index 6f0abe2..09db574 100644 --- a/runbooks/availability-failure.md +++ b/runbooks/availability-failure.md @@ -2,8 +2,9 @@ The **Link check** workflow (`.github/workflows/links.yml`) runs its `availability` job on a 6-hour schedule and on manual dispatch. It requests the live homepage, -`/stories/`, `/docs/`, `/llms.txt`, `/sitemap.xml`, `/robots.txt`, a sample of the shortcut redirects and `/404.html` over HTTPS and fails -unless every one returns HTTP 200. Use this runbook when that job is red and no recent +`/stories/`, `/docs/`, the `/code/`, `/discord/` and `/join/` shortcut redirects, +`/llms.txt`, `/sitemap.xml`, `/robots.txt`, `/.well-known/security.txt`, `/404.html` and +the `/software-factory/` project site over HTTPS and fails unless every one returns HTTP 200. Use this runbook when that job is red and no recent deploy explains it; for a bad commit, use the [rollback runbook](release-rollback.md). ## Who is affected @@ -33,6 +34,7 @@ probe runs (about 12 hours) should be treated as an outage, not a blip. | All paths fail, default `*.github.io` host also fails | GitHub Pages incident or failed Pages build | Check `gh api repos/hivecommons/hivecommons.github.io/pages/builds/latest`; wait for GitHub, or push a forward fix if the build error is ours | | Custom domain fails, default host works | `CNAME` missing or altered, DNS change, or expired/unprovisioned certificate | Confirm `CNAME` reads `hivecommons.dev`; review Settings → Pages for DNS or HTTPS warnings; re-save the custom domain to re-trigger certificate provisioning | | One or two paths return 404 | Redirect page or top-level page removed or renamed | Fix the `MAP` in `make-redirects.sh` and re-run `./make-redirects.sh`; do not hand-edit generated redirect pages | +| Only `/software-factory/` fails | That path is served by the sibling `hivecommons/software-factory` Pages repo, not this one | Triage in that repo's Pages settings and latest build; nothing here can fix it | | A path returns 5xx or times out intermittently | Pages/CDN degradation | Re-run after a few minutes; escalate only if it persists | | The probe URL list no longer matches the site | A probed page was intentionally removed | Update the list in the `availability` job and keep `scripts/availability-probes.test.mjs` passing; never drop a probe just to turn the job green | From 0b7874a083fedb05a28ab0749c6fcf0ced36254a Mon Sep 17 00:00:00 2001 From: operations <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 03:09:03 -0500 Subject: [PATCH 2/2] docs(runbooks): keep external /software-factory/ path out of code spans Signed-off-by: operations <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- runbooks/availability-failure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/runbooks/availability-failure.md b/runbooks/availability-failure.md index 09db574..41bd3f8 100644 --- a/runbooks/availability-failure.md +++ b/runbooks/availability-failure.md @@ -4,7 +4,7 @@ The **Link check** workflow (`.github/workflows/links.yml`) runs its `availabili job on a 6-hour schedule and on manual dispatch. It requests the live homepage, `/stories/`, `/docs/`, the `/code/`, `/discord/` and `/join/` shortcut redirects, `/llms.txt`, `/sitemap.xml`, `/robots.txt`, `/.well-known/security.txt`, `/404.html` and -the `/software-factory/` project site over HTTPS and fails unless every one returns HTTP 200. Use this runbook when that job is red and no recent +the software-factory project site (/software-factory/) over HTTPS and fails unless every one returns HTTP 200. Use this runbook when that job is red and no recent deploy explains it; for a bad commit, use the [rollback runbook](release-rollback.md). ## Who is affected @@ -34,7 +34,7 @@ probe runs (about 12 hours) should be treated as an outage, not a blip. | All paths fail, default `*.github.io` host also fails | GitHub Pages incident or failed Pages build | Check `gh api repos/hivecommons/hivecommons.github.io/pages/builds/latest`; wait for GitHub, or push a forward fix if the build error is ours | | Custom domain fails, default host works | `CNAME` missing or altered, DNS change, or expired/unprovisioned certificate | Confirm `CNAME` reads `hivecommons.dev`; review Settings → Pages for DNS or HTTPS warnings; re-save the custom domain to re-trigger certificate provisioning | | One or two paths return 404 | Redirect page or top-level page removed or renamed | Fix the `MAP` in `make-redirects.sh` and re-run `./make-redirects.sh`; do not hand-edit generated redirect pages | -| Only `/software-factory/` fails | That path is served by the sibling `hivecommons/software-factory` Pages repo, not this one | Triage in that repo's Pages settings and latest build; nothing here can fix it | +| Only the software-factory project site (/software-factory/) fails | That path is served by the sibling `hivecommons/software-factory` Pages repo, not this one | Triage in that repo's Pages settings and latest build; nothing here can fix it | | A path returns 5xx or times out intermittently | Pages/CDN degradation | Re-run after a few minutes; escalate only if it persists | | The probe URL list no longer matches the site | A probed page was intentionally removed | Update the list in the `availability` job and keep `scripts/availability-probes.test.mjs` passing; never drop a probe just to turn the job green |