From 870e73b18ad98b73ea99a1f3430b2b6df4bc7e14 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] 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/`.