--- title: Wiki publishing pipeline --- flowchart LR accTitle: GitHub Pages Publishing for the NutsNews Wiki accDescr { Reviewed wiki sources pass the complete quality gate, emit an exact ready commit, build and inspect an immutable artifact, and deploy to the default GitHub Pages URL. Production cutover adds only a DNS-only wiki CNAME, deploys the root artifact, configures the custom domain, waits for HTTPS, and performs public smoke tests or rolls back to the default URL. } change["Reviewed source or site-code change"] --> quality["Quality: contracts, fixtures, build, browser"] quality --> ready{"All gates pass?"} ready -->|No| fix["Fix source; rerun complete gate"] fix --> quality ready -->|Yes| sha["Emit validated SHA"] sha --> exact["Check out and verify exact SHA"] exact --> build["Build allowlisted site and base"] build --> inspect["Stamp commit; inspect budgets and final artifact"] inspect --> upload["Upload pinned Pages artifact"] upload --> deploy["Deploy through main-only environment"] deploy --> default["Smoke default /nutsnews-docs URL"] default --> launch{"Production launch approved?"} launch -->|No| default launch -->|Yes| dns["Set only DNS-only CNAME wiki to ramideltoro.github.io"] dns --> root["Deploy validated production-root artifact"] root --> domain["Set Pages custom domain"] domain --> https["Wait for certificate; enforce HTTPS"] https --> smoke{"Production smoke passes?"} smoke -->|Yes| live["Launch verified"] smoke -->|No| rollback["Redeploy pre-cutover artifact; remove custom domain; repair only wiki CNAME"]

GitHub Pages publishing for the NutsNews wiki

The repository is the source of truth. Astro builds the docs into static files, and GitHub Actions publishes only a checked artifact.

Where the wiki is now

Before cutover: https://ramideltoro.github.io/nutsnews-docs/
After cutover: https://wiki.nutsnews.com/
The custom domain stays unset until the launch gate.

Do not edit _site/, generated content, reports, caches, or the live Pages files.

Preview and check locally

npm ci
npm run dev -- --host 127.0.0.1 --port 4321

For a production preview:

npm run build
npm run preview -- --host 127.0.0.1 --port 4321

Run the documentation and browser gates:

npm run wiki:prepare
npm run validate:content
npm run validate:links
npm run validate:mermaid
npm run test:content-routes
npm run test:workflow
npm run test:pages-artifact
npm run test:browser
npm run build

What Actions does

Pull requests run checks but never deploy.

A push or manual run on main follows this order:

Check the 227 sources, both mirror sets, approvals, diagrams, links, secrets, routes, build, budgets, accessibility, keyboard flows, and screenshots.
Mark the exact commit as ready only after every check passes.
Check out that same commit in the Pages build.
Build, stamp, and inspect the final artifact.
Upload it.
Deploy it from the main-only Pages environment.

Only deployment can write to Pages. The workflow does not use a repository secret or an OpenAI key.

Launch order

Finish every platform and local QA gate. Smoke-test the default URL.
Prepare and fully validate the production-target site-code pull request, but do not merge it.
In Cloudflare, change only this record:

Type Name Target Proxy
CNAME wiki ramideltoro.github.io DNS only

Do not change any other DNS record.
Merge the ready production-target pull request and wait for its root artifact to deploy.
Set the repository Pages custom domain to wiki.nutsnews.com.
Wait for GitHub’s certificate, then turn on Enforce HTTPS.
Test the release stamp, root, both audiences, search/History, diagrams, 404, and nested pages.

Type	Name	Target	Proxy
CNAME	`wiki`	`ramideltoro.github.io`	DNS only

Rollback

Rollback verification contract

Record the last-good commit SHA first. Verify https://wiki.nutsnews.com serves it after a production rollback and test both audiences; after a cutover fallback, verify the default project URL instead.

For a bad production release, revert or rerun the last good commit, require every gate, confirm release.json, and smoke the affected routes.

For a failed domain cutover:

Redeploy the last pre-cutover /nutsnews-docs artifact.
Remove the repository custom domain and verify the default URL.
Remove or correct only the wiki CNAME if DNS caused the failure.
Leave every other DNS record unchanged and repeat the full gate.

When something fails

Quality: check approval, inventory, mirrors, diagrams, links, or browser results.
Build: check the exact commit, site/base, Astro, Pagefind, and budgets.
Artifact: check the stamp and blocked secret/env/source/CNAME files.
Deploy: check the main environment, Pages status, permissions, and artifact.
Domain: check the one DNS-only CNAME, custom-domain status, certificate, and HTTPS.

Fix the source and rerun. Do not edit deployed HTML or use .wiki-build, wiki-push, Jekyll, or bundle commands.

Primary diagram