ci(pages): dev.neotoma.io deploy failing — GitHub Pages artifact rejection + stuck build

[markmhendrickson]

Problem

GitHub emailed multiple Run failed: pages build and deployment notifications for markmhendrickson/neotoma-dev-site on 2026-06-25 and 2026-06-26. The custom domain dev.neotoma.io remains broken.

Current state (2026-06-29)

• GitHub Pages site status: errored (GET /repos/markmhendrickson/neotoma-dev-site/pages)
• Latest pages build (PHONE:09e8) has been stuck in building since 2026-06-26T10:16:44Z (commit 2b120f4)
• Prior builds show Page build failed.

Root cause (from workflow logs)

The pages-build-deployment workflow build job succeeds but the deploy job fails at "Deploy to GitHub Pages":

Artifact could not be deployed. Please ensure the content does not contain any hard links, symlinks and total size is less than 10GB.

Example failed run: PHONE:fc65 (2026-06-26).

The gh-pages branch tree is very large (~73k+ entries, API response truncated). Likely causes:

1. Artifact size approaching/exceeding GitHub Pages 10GB artifact limit (accumulated PR previews / locale exports)
2. Undetected symlinks or hard links in exported site output (none found in first API page, but tree is truncated)
3. Stuck build — latest build never completed, leaving site in limbo

Prior related issue

#1599 (closed) tracked an expired DEV_PAGES_DEPLOY_TOKEN. That was a different failure mode; this appears to be artifact/content rejection after token fix.

Recommended fix

1. Audit gh-pages branch size and prune stale PR preview directories (Docs PR preview cleanup workflow may also need hardening — it hit No space left on device on a runner during checkout on 2026-06-25, run PHONE:08f3).
2. Add CI guard: fail site export if artifact exceeds a safe threshold or contains symlinks.
3. Manually cancel/retrigger Pages build after cleanup; verify dev.neotoma.io returns 200.

Note

neotoma-dev-site has GitHub Issues disabled — tracking here in neotoma.

Environment

• Repo: markmhendrickson/neotoma-dev-site (tracked in markmhendrickson/neotoma)
• Client: cursor-agent