pages.yml

# Publish the committed evidence page to GitHub Pages.
#
# This workflow uploads a file. It does not build one.
#
# `site/index.html` is committed, reviewed in a diff like anything else, and
# generated by ./site_build.py from the evidence bundle. A deploy that
# regenerated the page could serve something no reviewer ever saw, which for a
# project whose argument is "we do not say untested things" would be the worst
# possible place to be casual. So the deploy's only relationship with the
# generator is `--check`: re-render from the committed evidence, compare to the
# committed file, and refuse to publish if they differ.
#
# That check is not this workflow's alone. tests/test_site.py runs both halves
# of it offline in the `core` job — the staleness diff and, separately, an
# independent parse of the HTML held against items.jsonl, responses.jsonl and
# baseline.json — and `core` is a required context in the ruleset. So a drift
# fails the pull request before it can reach a deploy. Running `--check` again
# here is the fail-closed half: neither the gate nor the deploy depends on the
# other having been run.
#
# Pages must be enabled in repository settings (Settings > Pages > Source:
# GitHub Actions) before this can deploy. It was enabled on 2026-08-16 and the
# first deploy succeeded the same day. If it is ever disabled again, this
# workflow still runs the verification and the deploy step fails, which is
# the correct report for "the site is not published".
#
# Every action is pinned to a commit rather than a tag. The argument is
# plumbline.pin's, applied here: a tag can be moved, and a green deploy today
# that quietly means something else tomorrow is not a record of anything.

name: pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

# One deploy at a time, and a superseded one is cancelled rather than racing
# the newer one to the same URL.
concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  publish:
    name: pages (verify the committed page, then upload it)
    runs-on: ubuntu-latest
    permissions:
      contents: read # the committed page, and the evidence it is checked against
      pages: write # publish the artifact; the only write here, and not to the repo
      id-token: write # deploy-pages authenticates by OIDC rather than a stored secret
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          # Nothing here pushes, so the deploy has no use for a credential
          # left behind in .git/config.
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"

      # Fail closed. If the committed page is not what the committed evidence
      # renders to, nothing is published: a stale demonstration page is a
      # published claim about answers that were never given.
      - name: The committed page still matches the committed evidence
        run: python3 site_build.py --check

      # The parse-and-compare half, which the staleness check above cannot do
      # because it asks the generator. Run here as well as in `core` so this
      # workflow does not publish on the strength of a job it did not run.
      - name: The page quotes the evidence, checked without the generator
        run: python3 -m unittest tests.test_site -v

      - name: Configure Pages
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

      - name: Upload the committed page
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: site

      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0