bug: GitHub Pages serves stale deployment — new pages 404 despite gh-pages branch being up to date

[planetf1]

Problem

Newly published pages return 404 on ibm-granite.github.io even though the gh-pages branch contains the files. GitHub Pages keeps serving an old deployment and does not pick up new pushes to the branch.

Observed 2026-08-25: after a successful deploy run (32862679742) that force-pushed gh-pages to a commit containing granite/docs/models/granite4-2.html, the page returned 404:

$ curl -sI https://ibm-granite.github.io/docs/granite/docs/models/granite4-2.html
HTTP/2 404
x-origin-cache: HIT        # GitHub origin serving a cached 404
etag: "6a887015-24a3"      # same ETag as the 404 page, not the content

Meanwhile the branch was correct:

$ git ls-tree -r origin/gh-pages --name-only | rg granite4-2
granite/docs/models/granite4-2.html

Evidence

The deployment API showed the most recent Pages deployment was from 2026-07-27 (SHA fedb17c), nearly a month before the push:

$ gh api repos/ibm-granite/docs/deployments?per_page=3 --jq '.[] | {id, sha, created_at}'
{"created_at":"2026-07-27T14:40:13Z","id":5624403112,"sha":"fedb17c..."}

The deploy job log confirmed the push succeeded but no new Pages deployment was created:

+ fedb17c...4b9ddc8 gh-pages -> gh-pages (forced update)
[INFO] Action successfully completed

The stale deployment served old pages fine (granite4-1.html → 200) but 404'd on anything added since 2026-07-27.

Root cause

The workflow uses peaceiris/actions-gh-pages with force_orphan: true. Every deploy creates a brand-new orphan commit (no parent). GitHub Pages' deployment hook does not reliably fire on orphan force-pushes — the branch updates, but Pages never creates a new deployment, so the live site stays on the last deployment Pages actually processed.

Workaround

Re-run the deploy job (or the whole workflow) from the Actions tab. The manual rerun creates a fresh Pages deployment that picks up the current branch head. Confirmed working: after re-running, granite4-2.html returned 200 with a fresh last-modified timestamp.

Recommended fix

Migrate to GitHub's native Pages deployment actions so a deployment is created explicitly and awaited on every push — see #68 (actions/upload-pages-artifact + actions/deploy-pages). This removes the orphan-push flakiness entirely and gives atomic deployments plus deployment environments.