Document why Pages is off and the Doxygen deploy fails - #16
Merged
Merged
Conversation
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
zeyuyang42
force-pushed
the
document-pages-decision
branch
from
August 25, 2026 15:33
5cfc1f8 to
1a1f0bf
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation only. No behaviour change — the Doxygen deploy still fails, deliberately.
Why
Deploy Doxygen documentationfails on every push tomaintouchingcore/include/**ordocs/**. Without a written reason that reads as a neglected build. It is a decision: enabling Pages publishes a page under the organization's website, which is the org owner's call to make and not something to land as a side effect of a CI change.What's here
docs/design/github-pages-deployment.md— the decision, what actually fails, and how to enable it once approved.Worth stating plainly, because the red X overstates the damage: only the deploy fails.
Generate documentationsucceeds — the HTML is built and then discarded. Runningdoxygen docs/Doxyfilelocally produces the full output underdocs/build/html.The doc also records why no workflow-side fix exists, so this isn't attempted a third time:
GET /repos/ringbuffer-org/Zerr/pages→404.actions/configure-pagesdefaults toenablement: false, which only queries for a site →Get Pages site failed / HttpError: Not Found.enablement: truefails too — creating a site needs admin repo permission, andadministrationis not a scope a workflow'spermissions:block can grant toGITHUB_TOKEN→Create Pages site failed / HttpError: Resource not accessible by integration.Both failures are cited to their runs. The token category is simply wrong for the operation; no configuration change fixes it.
Correction to PR #15
The comment I added above
Configure Pagesclaimedenablement: true"keeps the deploy self-contained instead of depending on someone having clicked through repository settings." That was written before the attempt, and the run disproved it. It now says the step is expected to fail and points at the design doc.The
enablement: trueparameter itself stays. It is inert but harmless — once a site exists the action's initialGetsucceeds andCreateis never reached — so keeping it means no edit is needed here if Pages is switched on later.When you're ready to enable it
Either Settings → Pages → Source: GitHub Actions, or
gh api -X POST repos/ringbuffer-org/Zerr/pages -f build_type=workflowwith an admin token. The workflow passes as written.One gotcha captured in the doc: its
pushtrigger is filtered tocore/include/**anddocs/**, so a settings-only change won't re-trigger it — dispatch manually to confirm.🤖 Generated with Claude Code