Skip to content
NutsNews chestnut logoNutsNews Wiki

Technical guide · Contributing

Page status: Active

GitHub Pages Publishing for the NutsNews Wiki

Preview, validate, stage, launch, verify, and roll back the static NutsNews Wiki on GitHub Pages.

Visual overview

Primary diagram

System map

A merged NutsNews pull request is discovered centrally. Codex drafts only documentation without a GitHub write token. A fixed path boundary records immutable merge provenance and runs the complete gate before committing to main. The existing exact-SHA Pages workflow then builds, inspects, and deploys the HTTPS wiki. Failures retain the prior site and cursor, cap an identical batch at three attempts, and resume when a newer merge appears.

Render the repository-owned system map when you need it.

Diagram is not rendered yet.

View as text
GitHub Pages Publishing for the NutsNews Wiki

A merged NutsNews pull request is discovered centrally. Codex drafts only documentation without a GitHub write token. A fixed path boundary records immutable merge provenance and runs the complete gate before committing to main. The existing exact-SHA Pages workflow then builds, inspects, and deploys the HTTPS wiki. Failures retain the prior site and cursor, cap an identical batch at three attempts, and resume when a newer merge appears.

---
title: Wiki publishing pipeline
---

flowchart LR
  accTitle: GitHub Pages Publishing for the NutsNews Wiki
  accDescr {
    A merged NutsNews pull request is discovered centrally. Codex drafts only documentation without a GitHub write token. A fixed path boundary records immutable merge provenance and runs the complete gate before committing to main. The existing exact-SHA Pages workflow then builds, inspects, and deploys the HTTPS wiki. Failures retain the prior site and cursor, cap an identical batch at three attempts, and resume when a newer merge appears.
  }
  merge["Merged PR in a NutsNews repository"] --> discover["Central five-minute discovery"]
  discover --> evidence["Bounded PR and patch evidence"]
  evidence --> codex["Codex drafts complete bundle without write token"]
  codex --> boundary{"Allowed documentation paths only?"}
  boundary -->|No| incident["Block, retain cursor, report incident"]
  boundary -->|Yes| provenance["Record repo, PRs, SHA, run, and source hash"]
  provenance --> quality["Quality: contracts, fixtures, build, browser"]
  quality --> ready{"All gates pass?"}
  ready -->|No| incident
  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 --> smoke{"Production HTTPS smoke passes?"}
  smoke -->|Yes| live["wiki.nutsnews.com updated"]
  smoke -->|No| rollback["Keep or restore last-good release"]

GitHub Pages Publishing for the NutsNews Wiki

Fullscreen diagram view.

GitHub Pages publishing for the NutsNews wiki

Section titled “GitHub Pages publishing for the NutsNews wiki”

The repository is the source of truth. Astro/Starlight builds a pure-static artifact, Pagefind indexes it, and the pinned .github/workflows/wiki-pages.yml workflow deploys it to GitHub Pages.

Current production state

Section titled “Current production state”
  • Production URL: https://wiki.nutsnews.com/
  • Release target: production in scripts/wiki/wiki-release.json
  • Build site/base: https://wiki.nutsnews.com and /
  • Pages custom domain: wiki.nutsnews.com
  • HTTPS enforcement: enabled

The tracked root CNAME records the intended hostname. GitHub Pages receives only the inspected static artifact.

Automatic documentation after NutsNews merges

Section titled “Automatic documentation after NutsNews merges”

.github/workflows/automated-merge-docs.yml polls every five minutes. It discovers every active public repository owned by ramideltoro whose name is nutsnews or begins with nutsnews-, excluding this documentation repository. New repositories are baselined automatically, so no per-repository workflow or duplicated secret is required.

For each repository with new merged pull requests, the workflow:

  1. checks out the exact latest merge and gathers bounded PR metadata and patches
  2. runs the pinned openai/codex-action with the repository secret OPENAI_API_KEY
  3. requires a per-repository merge-log entry and updates any directly stale operating docs
  4. rejects deletion, tooling changes, or any path outside canonical Markdown, its two mirrors, review manifest, and Mermaid diagram
  5. records automated approval provenance after Codex exits; Codex never receives a GitHub write token
  6. runs contracts, content, approval, link, Mermaid, secret, and production-build gates
  7. commits directly to main, advances the merge cursor, and dispatches the Pages workflow

The cursor advances only after success. A failure leaves the cursor unchanged and opens or updates a GitHub incident. The same merge batch retries at most three times to bound API spend; a later merge automatically resumes a paused repository and includes the still-pending changes. PR text, patches, source files, and repository instruction files are untrusted evidence, never instructions.

Owned paths

Section titled “Owned paths”

The publishing contract is implemented by:

  • .github/workflows/wiki-pages.yml
  • astro.config.mjs
  • playwright.config.mjs
  • package.json and package-lock.json
  • scripts/wiki/wiki-release.json
  • scripts/wiki/validate-pages-artifact.mjs
  • scripts/wiki/validate-wiki-budgets.mjs
  • scripts/wiki/validate-wiki-secrets.mjs
  • tests/wiki/reader-journeys.spec.mjs
  • CNAME

Canonical Markdown, Simple/Technical mirrors, diagrams, and approval metadata are sources. src/content/docs/, _site/, playwright-report/, test-results/, caches, and the generated inventory are outputs; do not edit or commit them.

Local preview

Section titled “Local preview”

Install the locked dependencies:

Terminal window
npm ci

For an authoring preview:

Terminal window
npm run dev -- --host 127.0.0.1 --port 4321

For a root-form production preview:

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

For the actual pre-cutover project-path artifact:

Terminal window
WIKI_SITE_URL=https://ramideltoro.github.io WIKI_BASE_PATH=/nutsnews-docs npm run build
npm run wiki:release:stamp -- --sha="$(git rev-parse HEAD)"
WIKI_SITE_URL=https://ramideltoro.github.io WIKI_BASE_PATH=/nutsnews-docs npm run validate:pages-artifact -- --sha="$(git rev-parse HEAD)"
npm run preview -- --host 127.0.0.1 --port 4321

Open http://127.0.0.1:4321/nutsnews-docs/ for that project-path preview.

Local validation

Section titled “Local validation”

Run these commands from the repository root:

Terminal window
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

The complete content gate requires at least the 227-source v1 baseline and then checks every current canonical source, both mirror sets, current human or merge-provenance approvals, one accessible diagram per source, unique routes/orders, links/fragments, images, and orphans. Broken fixtures must exit nonzero.

GitHub Actions order

Section titled “GitHub Actions order”

The workflow runs for every pull request, relevant push to main, and manual workflow_dispatch. Superseded runs on the same ref cancel. Every GitHub-authored Action is pinned to a full release SHA.

Pull request

Section titled “Pull request”

Only the quality job runs. It installs with npm ci, exercises authoring and broken fixtures, validates source/content/link/secret/Mermaid contracts, builds the root-form site, enforces budgets, validates built surfaces, and runs the three-viewport Playwright/axe/visual suite. A passing PR does not deploy.

Push or manual run on main

Section titled “Push or manual run on main”
  1. The quality job completes and emits validated_sha only after every gate passes.
  2. The build job depends on that output, checks out the exact SHA, and verifies both GITHUB_SHA and git rev-parse HEAD.
  3. Astro builds with the allowlisted site/base for the current release target.
  4. release.json is stamped with the exact validated SHA.
  5. Budgets and validate:pages-artifact inspect the final upload directory.
  6. The pinned Pages artifact Action uploads _site/.
  7. The deploy job, restricted to main by the github-pages environment, deploys that artifact.

Global token access is contents: read. Only the deploy job has pages: write and id-token: write. The Pages workflow consumes no OpenAI key; only the separate merge-documentation workflow uses it. Failure-only browser artifacts contain only the two Playwright output directories, exclude hidden files, and expire after seven days.

Launch gate and production cutover

Section titled “Launch gate and production cutover”

Do not start the cutover until all platform issues and local launch QA are complete and the default URL passes public smoke tests.

  1. Prepare a normal site-code pull request that changes the release target from project Pages to production root:

    • .github/workflows/wiki-pages.yml: WIKI_SITE_URL=https://wiki.nutsnews.com, WIKI_BASE_PATH=/
    • scripts/wiki/wiki-release.json: mode production, site URL https://wiki.nutsnews.com, base /, public URL https://wiki.nutsnews.com/
    • scripts/wiki/validate-pages-artifact.mjs and its tests: accept and enforce the production target

  2. Validate that pull request completely, but do not merge it yet.

  3. In Cloudflare, add or update only this DNS record:

    TypeNameTargetProxy
    CNAMEwikiramideltoro.github.ioDNS only

    Do not add, delete, or modify any other DNS record.

  4. Merge the validated production-target pull request. Wait for its root-form Pages artifact to deploy successfully.

  5. In repository Settings → Pages, set the custom domain to wiki.nutsnews.com. Do not change the Actions build source.

  6. Wait for GitHub Pages to approve the certificate, then enable Enforce HTTPS.

  7. Verify DNS, HTTPS, the exact release stamp, root routing, both audiences, search/History, diagrams, 404, and representative nested pages before declaring launch complete.

Useful read-only checks:

Terminal window
dig +short CNAME wiki.nutsnews.com
curl --fail --location --silent --show-error https://wiki.nutsnews.com/release.json
curl --fail --location --silent --show-error --output /dev/null https://wiki.nutsnews.com/simple/project/
curl --fail --location --silent --show-error --output /dev/null https://wiki.nutsnews.com/technical/project/

Rollback

Section titled “Rollback”

Rollback verification contract

Section titled “Rollback verification contract”

Record the last-good commit SHA before either rollback path. Verify https://wiki.nutsnews.com serves that stamped SHA after a production rollback and smoke both audiences; after a cutover fallback, verify the default project URL instead.

Bad content or site release

Section titled “Bad content or site release”
  1. Identify the last successful production run and its stamped commit.
  2. Revert the bad commit on main through the contribution workflow that applies to the changed paths, or rerun the last known-good workflow run.
  3. Require quality, exact-SHA, artifact, and deploy jobs to pass.
  4. Confirm release.json reports the intended commit, then smoke both audiences and the affected routes.

Failed custom-domain cutover

Section titled “Failed custom-domain cutover”
  1. Redeploy the last successful pre-cutover commit so the artifact again uses /nutsnews-docs.
  2. Remove the repository Pages custom domain and verify https://ramideltoro.github.io/nutsnews-docs/.
  3. Remove or correct only the wiki CNAME if DNS itself caused the failure; leave every other DNS record unchanged.
  4. Diagnose and repeat the full cutover gate instead of patching deployed HTML.

Failure handling

Section titled “Failure handling”
Failure stageCheck first
Qualitystale approval, incomplete inventory, mirror/diagram/link defect, broken fixture, axe/visual failure
Exact buildmissing validated_sha, mismatched checkout SHA, wrong site/base, Astro or Pagefind failure
Artifactsecret/env/source file, hidden path, symlink, CNAME claim, wrong stamp, missing route, budget
Deploymain environment policy, Pages status, deployment-only permissions, artifact availability
Default URLproject base /nutsnews-docs, asset paths, root audience redirect, release stamp
Custom domainthe single DNS-only CNAME, Pages custom-domain state, certificate state, HTTPS enforcement

Fix the source, config, or external setting and rerun the complete workflow. Never edit deployed HTML, weaken a gate, expose logs/artifacts containing secrets, or use obsolete .wiki-build, wiki-push, Jekyll, or bundle commands.