How this site is built

A static site, in one repository, deployed by GitHub Pages from the dev branch. There is no framework, no build step you have to install, and no server. What there is is a release pipeline that refuses to publish a site that fails its own checks — and that pipeline is the first thing this site shipped, before it had any content to publish.

The pipeline: three jobs, each gating the next

One workflow, .github/workflows/deploy-pages.yml, on every push to dev and main, on every pull request against them, and on manual dispatch.

# push to dev
validate ──▶ tag-release ──▶ deploy
   │             │                │
   │             │                └─ upload-pages-artifact, deploy-pages
   │             └─ git push origin refs/tags/vX.Y.Z
   └─ gen_*.py --check ; node admin/build/validate.js

# pull request  → validate only (no tag, no deploy)
# push to main  → validate, deploy; tag-release skips
# dispatch      → validate, deploy; tag-release skips

main is deploy-only, on purpose. tag-release is gated on refs/heads/dev, so a push to main validates and publishes without writing a tag. That makes main usable as a deploy test or a fallback without polluting the tag history.

The release gate

admin/build/validate.js is plain Node with no dependencies, so it runs anywhere Node exists. Four checks, in order, and any failure exits non-zero:

The leak tripwire

A site about how software gets written quotes real sessions, real configuration and real terminal output — that is the point of it. It is also the one way this repository could publish something it cannot take back. So the gate scans every file in the tree, not just the HTML, for a handful of credential shapes:

• an sgit vault key — a long passphrase joined by a colon to a UUID-shaped id
• an AWS access key id (AKIA…, ASIA…)
• a GitHub token (ghp_, gho_, ghu_, ghs_, ghr_)
• an API secret key (sk-…, sk-ant-…)
• a PEM private key block
• a Slack token (xoxb- and friends)
• a bare 12-digit number — the shape of an AWS account id. Added in v0.2.0

The fix for a tripped wire is always to redact the snippet, never to widen the pattern. The one file exempt from the scan is validate.js itself, which necessarily carries the patterns — that exemption is what makes them writable at all.

How CI decides the tag

Every push to dev is a minor release. The version is owned by one file and stated twice, and CI refuses to tag unless both agree:

# 1. the file that owns it
admin/build/version.txt        v0.1.0

# 2. the release commit's subject
git commit -m "site v0.1.0: the pipeline, before the site"

# CI then checks, in this order:
newest release commit's version == version.txt   # or: error, the two disagree
tag vX.Y.Z sits on THAT commit                    # or: error, version was not bumped
vX.Y.Z is the next minor after the latest tag     # or a deliberate major to .0
git push origin refs/tags/vX.Y.Z                  # the load-bearing push

Three details are worth knowing, because each of them is a bug that was fixed once already on a sibling site:

• The release commit is not always HEAD. When a pull request lands as a merge commit, HEAD is the merge and the release commit is its parent. Every check anchors to the newest commit whose subject carries a version, not to HEAD.
• Historical tags are backfilled. On its first run the job reads the whole history and tags any commit whose subject carries a version it cannot find a tag for. It is idempotent, so it is a no-op on every run afterwards, and it checks the remote before pushing so it does not repeat work it has already done.
• A backfilled tag can be legitimately rejected. GITHUB_TOKEN cannot push a ref onto a commit whose tree carries a different .github/workflows blob. Those are reported as warnings and the job still succeeds — the release's own tag is the load-bearing one, and a human can complete the set with git push origin --tags.

What is generated, and how drift is caught

Anything that restates something else is generated from it. A hand-maintained twin of a file is a stale artefact with a longer fuse — the sitemap that forgets a page, the "full text" file that is missing three documents.

Each generator takes --check, which regenerates in memory and compares. CI runs all of them that way before validation, so a published page that has drifted from its source fails the build instead of quietly shipping.

One subtlety: the --check comparison ignores the nav and footer blocks. chrome.py rewrites those in place after generation, so comparing them would always differ on chrome alone. Stripping both blocks from both sides compares exactly what the generator is responsible for and nothing it is not.

The release checklist

Seven steps, in this order, and the order is load-bearing twice. gen_inline.py runs after the generators, because it writes into pages they have just produced. And the files that read the tree run after chrome has stamped the version, or they assemble a stale version line.

# 1. bump the version and add its row
admin/build/version.txt        # vX.Y.Z, exactly once per release
admin/versions.html            # a row saying what changed
admin/comms.html               # what is outstanding, if it changed

# 2. regenerate the pages
python3 admin/build/gen_documents.py
python3 admin/build/gen_rules.py

# 3. propagate nav, footer and the version badge everywhere
python3 admin/build/chrome.py

# 4. write every number and example in — AFTER the pages exist
python3 admin/build/gen_inline.py

# 5. regenerate what reads the tree — AFTER chrome
python3 admin/build/gen_llms_full.py
python3 admin/build/gen_sitemap.py

# 6. run exactly what CI runs
python3 admin/build/gen_documents.py --check
python3 admin/build/gen_rules.py     --check
python3 admin/build/gen_inline.py    --check
python3 admin/build/gen_llms_full.py --check
python3 admin/build/gen_sitemap.py   --check
node admin/build/validate.js

# 7. release
git commit -am "site vX.Y.Z: ..." && git push -u origin dev

The repository