Skip to content

fix(approuter): preserve static/qa across content-rebuild swap (recurring QA navigator wipe) - #1759

Merged
jung-thomas merged 1 commit into
DEVfrom
fix/qa-nav-preserve-on-content-rebuild
Aug 14, 2026
Merged

jung-thomas merged 1 commit into
DEVfrom
fix/qa-nav-preserve-on-content-rebuild

Conversation

@jung-thomas

Copy link
Copy Markdown
Contributor

Problem

/tutorials-qa/ (the QA author-preview tutorial navigator) keeps disappearing on PROD (404). Confirmed on live PROD (authenticated): the QA backend is healthy (/tutorials-qa/_nav.json → 200, 2071 tutorials; /qa-search → 200), but the entire static frontend under static/qa/ (index.html, js, css) 404s.

Root cause (the persistent one)

rebuild-content.yml's "Assemble static content" step (L707–728) builds the tarball from hugo/public/* + the admin/scanner/explore/analytics/data-inspector dirs (added in #350) but omits static/qa. The approuter's /admin/rebuild handler then does an atomic whole-dir swap (approuter/server.js:380–383: rename static → old, rename new → static, rm old). Anything not in the tarball — i.e. static/qa — is deleted from the running pod on every full/catalog-only content rebuild. static/qa is shipped only by the full MTA deploy (root mta.yaml builds hugo/public-qa inline), so it never comes back until the next deploy.

Fix

Preserve deploy-only static subtrees across the swap. REBUILD_PRESERVE_DIRS = ['qa']; after the swap, carry each forward from the previous static dir only when the incoming tarball didn't ship it (so a future tarball that includes static/qa still wins). QA nav is independent of content rebuilds by design, so preserving (rather than rebuilding it every time) is the correct coupling.

Scope / caveats

Follow-ups

  • Companion PR: local-deploy QA build + mtar-parity guard (static/qa/index.html present).
  • Consider extracting the preserve loop to a tested helper (handler isn't currently exported).

Part of the "recurring missing QA navigator" cleanup.

The /admin/rebuild handler atomically replaces the whole static dir with
the pushed tarball. rebuild-content.yml's 'Assemble static content' step
does NOT include static/qa (the QA author-preview navigator, shipped only
by the full MTA deploy via root mta.yaml's inline hugo/public-qa build), so
every full/catalog-only content rebuild WIPED static/qa off the running pod
-> /tutorials-qa/ 404s until the next deploy. This is the recurring 'no QA
navigator on PROD' root cause.

Carry deploy-only subtrees (REBUILD_PRESERVE_DIRS = ['qa']) forward from the
previous static dir across the swap, but only when the incoming tarball did
not ship them (so a future tarball that DOES include static/qa still wins).

Verification requires a deploy + a content rebuild (cannot be exercised by
unit tests / curl). Alternative considered: add a QA fetch+build+assemble to
rebuild-content.yml (matches the #350 include-in-tarball precedent) — heavier
(adds a full QA build to every prod rebuild); preserve is lighter and QA nav
is content-rebuild-independent by design.
@jung-thomas
jung-thomas merged commit dab0fd5 into DEV Aug 14, 2026
3 checks passed
@jung-thomas
jung-thomas deleted the fix/qa-nav-preserve-on-content-rebuild branch August 14, 2026 05:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant