From 9a1379c87f8df3611bac3e50a341f9adf752500c Mon Sep 17 00:00:00 2001 From: Zeyu Yang <40936154+zeyuyang42@users.noreply.github.com> Date: Wed, 19 Aug 2026 23:39:47 +0200 Subject: [PATCH 1/2] Document why Pages is off and the Doxygen deploy fails The `Deploy Doxygen documentation` job fails on every push to main touching core/include/** or docs/**, which reads as neglect unless the reason is written down. It is deliberate: enabling Pages publishes a page under the organization's website, and that is the org owner's decision to make rather than something to land as a side effect of a CI change. docs/design/github-pages-deployment.md records the decision, what actually fails (only the deploy -- Doxygen generation itself succeeds and the HTML is built, then discarded), and the two ways to enable it once approved. It also records why no workflow-side fix exists, so this is not attempted a third time: `actions/configure-pages` with the default enablement: false only queries for a site that has never existed, and enablement: true cannot create one either, because POST /repos/{owner}/{repo}/pages needs admin permission and `administration` is not a scope `permissions:` can grant to GITHUB_TOKEN. Both failures are cited to their runs. The comment above Configure Pages claimed enablement: true "keeps the deploy self-contained instead of depending on someone having clicked through repository settings". That was written before the attempt and is false; corrected to say the step is expected to fail and to point at the design doc. The parameter itself stays so the file needs no edit if Pages is enabled later. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/deploy-doxygen.yml | 17 ++++--- docs/design/github-pages-deployment.md | 66 ++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 7 deletions(-) create mode 100644 docs/design/github-pages-deployment.md diff --git a/.github/workflows/deploy-doxygen.yml b/.github/workflows/deploy-doxygen.yml index 1c11fa8..0d1893b 100644 --- a/.github/workflows/deploy-doxygen.yml +++ b/.github/workflows/deploy-doxygen.yml @@ -40,13 +40,16 @@ jobs: - name: Generate documentation run: doxygen docs/Doxyfile - # enablement: true creates the Pages site on first run. The default (false) - # only *queries* for an existing site, so on a repository where Pages was - # never turned on the action fails with "Get Pages site failed ... HttpError: - # Not Found" and every step after it is skipped -- which is exactly what - # happened the first time this workflow ran on main. Provisioning here keeps - # the deploy self-contained instead of depending on someone having clicked - # through repository settings; it uses the `pages: write` scope granted above. + # This step currently FAILS, and that is expected -- Pages is deliberately not + # enabled for this repository pending the organization owner's approval. See + # docs/design/github-pages-deployment.md before trying to fix it. + # + # `enablement: true` does not rescue it: creating a Pages site requires admin + # repository permission, and `administration` is not a scope a workflow's + # `permissions:` block can grant to GITHUB_TOKEN, so the call comes back + # "Resource not accessible by integration". It is kept only so that no edit is + # needed here once Pages is switched on out-of-band -- at which point the + # initial Get succeeds and Create is never reached. - name: Configure Pages uses: actions/configure-pages@v4 with: diff --git a/docs/design/github-pages-deployment.md b/docs/design/github-pages-deployment.md new file mode 100644 index 0000000..16b01db --- /dev/null +++ b/docs/design/github-pages-deployment.md @@ -0,0 +1,66 @@ +# GitHub Pages Deployment — Deliberately Not Enabled + +_Decision recorded 2026-08-19 · applies to `ringbuffer-org/Zerr`_ + +## Decision + +**GitHub Pages is not enabled for this repository, and the failing `Deploy Doxygen documentation` +workflow is accepted rather than fixed.** + +Enabling Pages publishes a new page under the organization's website +(`ringbuffer-org.github.io/Zerr`). That is the organization owner's call, and it should not happen +as a side effect of a CI change. Enabling it requires notifying the owner first. + +Do not "fix" the red Doxygen job without that approval. + +## Current behaviour + +`Deploy Doxygen documentation` fails on every push to `main` touching `core/include/**` or +`docs/**`, so `main` shows a recurring red X. + +Only the deploy fails. Doxygen itself is healthy: + +| Step | Result | +| --- | --- | +| Install Doxygen | success | +| Generate documentation | **success** | +| Configure Pages | **failure** | +| Upload Pages artifact | skipped | +| Deploy to GitHub Pages | skipped | + +The documentation builds correctly and is then discarded. Nothing is broken behind the failure — +running `doxygen docs/Doxyfile` locally produces the full HTML under `docs/build/html`. + +## Why the workflow cannot fix this itself + +This was attempted and does not work. The findings, so nobody re-derives them: + +1. **Pages has never been enabled.** `GET /repos/ringbuffer-org/Zerr/pages` returns `404`. +2. **`actions/configure-pages` defaults to `enablement: false`**, which only *queries* for an + existing site. With no site it fails: + `Get Pages site failed ... HttpError: Not Found`. +3. **`enablement: true` also fails.** Creating a site hits `POST /repos/{owner}/{repo}/pages`, + which requires **admin** repository permission — and `administration` is not among the scopes a + workflow's `permissions:` block can grant to `GITHUB_TOKEN`. Verified in + [run 32303359056](https://github.com/ringbuffer-org/Zerr/actions/runs/32303359056): + `Create Pages site failed ... HttpError: Resource not accessible by integration`. + +The `enablement: true` currently in `deploy-doxygen.yml` is therefore inert. It is harmless — once a +site exists the action's initial `Get` succeeds and it never reaches `Create` — and is left in place +so the workflow needs no edit if Pages is enabled later. + +**No workflow-side change can resolve this.** The token category is wrong for the operation. + +## How to enable it, once approved + +Either one, then re-run the workflow: + +- **Repository settings** — Settings → Pages → Source: **GitHub Actions** +- **API, with an admin-scoped token** — + `gh api -X POST repos/ringbuffer-org/Zerr/pages -f build_type=workflow` + +The workflow needs no changes; it will pass as written. Note that its `push` trigger is filtered to +`core/include/**` and `docs/**`, so a config-only change will not re-trigger it — dispatch it +manually (`gh workflow run "Deploy Doxygen documentation" --ref main`) to confirm. + +The published site would be `https://ringbuffer-org.github.io/Zerr/`. From 1a1f0bfcb57c9890363b91c197e3a1a4f268233d Mon Sep 17 00:00:00 2001 From: Zeyu Yang <40936154+zeyuyang42@users.noreply.github.com> Date: Tue, 25 Aug 2026 17:23:24 +0200 Subject: [PATCH 2/2] Record the 2026-08-24 Pages episode in the deployment doc Pages was enabled by hand on 2026-08-19 with source "Deploy from a branch", which made two things look true that are not. The Doxygen workflow went green on 87d6bf0 without having been fixed: once a site existed, configure-pages' initial query succeeded and the admin-only create call was simply never reached. And the site it published was a Jekyll rendering of the repository root, because branch mode leaves GitHub's legacy pages-build-deployment builder running -- it raced this workflow for the same environment and won by 16 seconds, deactivating the Doxygen deployment. That falsifies the doc's characterisation of `enablement: true` as an inert but harmless placeholder. It also cannot flip an existing site's build_type from legacy to workflow, so it offers no protection against exactly the misconfiguration that caused this. Enabling Pages is therefore not sufficient; the source must be "GitHub Actions". Also records the diagnostic trap that made the symptom ambiguous -- the Doxyfile's USE_MDFILE_AS_MAINPAGE means the correct Doxygen output also lands README prose on the landing page -- and rules out the organization-admin approval theory, since the github-pages environment has no required reviewers and the failing runs errored inside the job rather than parking for approval. Pages remains off and this PR remains unmerged, per the standing decision. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/deploy-doxygen.yml | 7 ++ docs/design/github-pages-deployment.md | 101 +++++++++++++++++++++++-- 2 files changed, 102 insertions(+), 6 deletions(-) diff --git a/.github/workflows/deploy-doxygen.yml b/.github/workflows/deploy-doxygen.yml index 0d1893b..cebc680 100644 --- a/.github/workflows/deploy-doxygen.yml +++ b/.github/workflows/deploy-doxygen.yml @@ -50,6 +50,13 @@ jobs: # "Resource not accessible by integration". It is kept only so that no edit is # needed here once Pages is switched on out-of-band -- at which point the # initial Get succeeds and Create is never reached. + # + # Do not read that as a safety net. It cannot switch an existing site's + # build_type from legacy to workflow either (that PUT needs admin too), so if + # Pages is enabled as "Deploy from a branch", GitHub's legacy Jekyll builder + # keeps running and races this job for the same environment -- on 2026-08-24 it + # won by 16 seconds and published a rendering of the repo root instead of the + # generated docs. Whoever enables Pages must choose source "GitHub Actions". - name: Configure Pages uses: actions/configure-pages@v4 with: diff --git a/docs/design/github-pages-deployment.md b/docs/design/github-pages-deployment.md index 16b01db..4ea6e71 100644 --- a/docs/design/github-pages-deployment.md +++ b/docs/design/github-pages-deployment.md @@ -1,6 +1,7 @@ # GitHub Pages Deployment — Deliberately Not Enabled -_Decision recorded 2026-08-19 · applies to `ringbuffer-org/Zerr`_ +_Decision recorded 2026-08-19 · revised 2026-08-25 after Pages was briefly enabled and turned back +off · applies to `ringbuffer-org/Zerr`_ ## Decision @@ -35,7 +36,9 @@ running `doxygen docs/Doxyfile` locally produces the full HTML under `docs/build This was attempted and does not work. The findings, so nobody re-derives them: -1. **Pages has never been enabled.** `GET /repos/ringbuffer-org/Zerr/pages` returns `404`. +1. **Pages is not enabled.** `GET /repos/ringbuffer-org/Zerr/pages` returns `404`. (It was enabled + between 2026-08-19 and 2026-08-25 — see the postmortem below — and has since been turned off + again, restoring the `404`.) 2. **`actions/configure-pages` defaults to `enablement: false`**, which only *queries* for an existing site. With no site it fails: `Get Pages site failed ... HttpError: Not Found`. @@ -45,12 +48,87 @@ This was attempted and does not work. The findings, so nobody re-derives them: [run 32303359056](https://github.com/ringbuffer-org/Zerr/actions/runs/32303359056): `Create Pages site failed ... HttpError: Resource not accessible by integration`. -The `enablement: true` currently in `deploy-doxygen.yml` is therefore inert. It is harmless — once a -site exists the action's initial `Get` succeeds and it never reaches `Create` — and is left in place -so the workflow needs no edit if Pages is enabled later. - **No workflow-side change can resolve this.** The token category is wrong for the operation. +The `enablement: true` currently in `deploy-doxygen.yml` is inert, and is left in place so the +workflow needs no edit once Pages is enabled out-of-band. It is *not*, however, a safety net: see +the next section for what it fails to do. + +## Postmortem — the 2026-08-24 green run that served the README + +Between 2026-08-19 21:20 UTC and 23:36 UTC, Pages was enabled by hand via **Settings → Pages → +Source: "Deploy from a branch"**. Nothing in this repository requested that; it was an out-of-band +click. Two things followed, and neither was what it looked like. + +### The workflow went green without being fixed + +[Run 32789021466](https://github.com/ringbuffer-org/Zerr/actions/runs/32789021466) (push of +`87d6bf0`, the #18 merge) passed end to end. `Configure Pages` logged no warning and no error. + +The workflow had not changed. `configure-pages` *queries* for a site before it tries to create one; +once the site existed the query succeeded, so the admin-only `POST` — the call that had been +failing — was simply never reached. **The precondition changed, not the workflow.** Point 3 above +still stands unaltered. + +It surfaced on 08-24 rather than 08-19 only because the workflow's `paths:` filter needs +`core/include/**` or `docs/**`, and `87d6bf0` was the first qualifying push afterwards. + +### The published site was the repository README, not the Doxygen output + +Because the source was **"Deploy from a branch"**, GitHub also runs its own legacy Jekyll builder +(`pages-build-deployment`, `actions/jekyll-build-pages@v1`) on every push to `main`. On `87d6bf0` +both ran concurrently and raced for the same `github-pages` environment: + +| Time (UTC) | Event | +| --- | --- | +| 23:22:15 | `Deploy Doxygen documentation` **and** `pages-build-deployment` both start | +| 23:22:44 | Doxygen `deploy-pages` reports success | +| 23:22:47 | Doxygen deployment goes **live** | +| 23:22:54–23:23:02 | legacy Jekyll `deploy` job runs | +| 23:23:03 | Jekyll deployment goes **live** | +| 23:23:04 | the earlier deployment is marked **inactive** | + +The Doxygen deploy was correct — its artifact held 213 files (`annotated.html`, `hierarchy.html`, +`files.html`, every `classzerr_1_1*` page). **It lost the race by 16 seconds and was deactivated.** + +The winner published the raw repository root: `index.html` rendered from `README.md`, plus +`CLAUDE.html`, `build.sh`, `conanfile.txt`, `configs/*.yaml`, and every submodule's documentation +(`puredata/pd-lib-builder/tests/*/index.html`, `maxmsp/source/min-api/doc/*.html`). + +### What this adds to point 3 + +`enablement: true` does not merely fail to *create* a site. It also fails to switch an existing +site's `build_type` from `legacy` to `workflow` — that `PUT` needs admin as well — which is exactly +why the Jekyll builder kept running alongside the Doxygen deploy. The setting neither provisions nor +configures; it only stops erroring once a human has done the work in Settings. + +So **"enable Pages" is not sufficient. The source must be "GitHub Actions".** Enabling it in branch +mode produces a green workflow and a wrong website, which is worse than the honest red X. + +### Diagnostic trap: the Doxygen landing page also looks like the README + +`docs/Doxyfile` sets `INPUT = core/include/ README.md` and `USE_MDFILE_AS_MAINPAGE = README.md`, and +the generated artifact contains no `md_README.html` — the README is consumed *as* the Doxygen main +page and rendered into `index.html`. So README prose on the landing page does **not** by itself mean +the wrong builder won. + +The tell is the chrome: the Doxygen page carries the treeview sidebar and links to `annotated.html`; +the Jekyll page is bare primer-themed markdown with no class documentation anywhere. + +### Ruled out + +The green run was **not** an approval by an organization admin. The `github-pages` environment has a +single `branch_policy` protection rule and **no required reviewers**, its `approvals` endpoint +returns `[]`, and the run went from `created_at` to `updated_at` in 32 seconds without ever parking. +Decisively, the earlier failures did not stall awaiting anyone — they executed and failed *inside* +the job with an API error, which an approval gate cannot produce. + +Nor did it need an owner's intervention: the maintainer already holds `admin: true` on this +repository, so the Settings click was directly available. Who made it could not be established — the +`dynamic` builder runs are attributed to the pusher of the triggering commit, not to whoever changed +the setting, and `orgs/ringbuffer-org/audit-log` returns `404` (it needs both an Enterprise-plan +organization and a `read:audit_log` token), so that check could not be performed. + ## How to enable it, once approved Either one, then re-run the workflow: @@ -59,8 +137,19 @@ Either one, then re-run the workflow: - **API, with an admin-scoped token** — `gh api -X POST repos/ringbuffer-org/Zerr/pages -f build_type=workflow` +> **The source must be "GitHub Actions", not "Deploy from a branch".** Branch mode leaves GitHub's +> legacy Jekyll builder running, which will race this workflow and overwrite the documentation with +> a rendering of the repository root. See the postmortem above. + The workflow needs no changes; it will pass as written. Note that its `push` trigger is filtered to `core/include/**` and `docs/**`, so a config-only change will not re-trigger it — dispatch it manually (`gh workflow run "Deploy Doxygen documentation" --ref main`) to confirm. +Verify afterwards that no `pages-build-deployment` run appears alongside it; one appearing means the +source is still branch mode. + +```bash +gh api "repos/ringbuffer-org/Zerr/actions/runs?event=dynamic" --jq '.total_count' # expect 0 new +``` + The published site would be `https://ringbuffer-org.github.io/Zerr/`.