GitHub Action — the freshness loop

examples/github-workflows/specreel.yml turns the demo into something that can't be older than your last passing build: on every push to main it regenerates the gallery and publishes it to GitHub Pages, and on every pull request it posts a preview.

What it does

  • Push to main → run your Playwright tests → build the gallery → publish to GitHub Pages. The demo is always the latest green build.
  • Pull request → build the gallery bundle → upload it as an artifact → upsert a single sticky PR comment with a per-flow summary (pass / updated / failed).

The one-line reusable action

Don't want to copy the whole workflow? Use the composite action (action.yml at the repo root) — it sets up Python, builds the gallery, and optionally publishes, in one step:

name: demos
on:
  push: { branches: [main] }
permissions: { contents: read, pages: write, id-token: write }
jobs:
  demos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx playwright install --with-deps chromium && npx playwright test || true
      - uses: your-org/specreel@v1            # the reusable action
        with:
          traces: test-results
          bundle: "true"
          publish: cloud                       # or: ghpages | none
          cloud-url: ${{ secrets.SPECREEL_CLOUD_URL }}
          token: ${{ secrets.SPECREEL_CLOUD_TOKEN }}
          project: my-app

Inputs: traces, out, bundle, theme, ai (+ anthropic-api-key), url, notify, publish (none/ghpages/cloud) and cloud-url/token/project. Output: gallery (the built directory). The action bundles specreel.py, so there's nothing to pip install.

Setup (full workflow)

  1. Enable Pages: Settings → Pages → Source: GitHub Actions.
  2. Make sure your Playwright config has tracing on (use: { trace: 'on' }, or --tracing on for pytest) so test-results/**/trace.zip exists.
  3. Edit the "Run Playwright tests" step to your real test command.
# excerpt — see examples/github-workflows/specreel.yml for the full file
on:
  push: { branches: [main] }
  pull_request:
permissions:
  contents: read
  pages: write
  id-token: write
  pull-requests: write

The PR comment is generated by specreel.py summary <site>, so you can reproduce or customize it in any CI:

python specreel.py summary _site --url "$PREVIEW_URL"

Reusing an existing test job

If another workflow already runs your Playwright tests and uploads the traces, delete the "Run Playwright tests" block and download that artifact into test-results/ instead (a commented download-artifact step shows where).