Migrate PR-preview workflow to Morrison-Lab/gha's preview family (preview.yml@v2 + preview-deploy.yml@v2)

[d-morrison]

Summary

.github/workflows/preview.yml builds and deploys a Quarto PR preview in a single job, using rossjrw/pr-preview-action. Morrison-Lab/gha ships this as a 4-workflow family instead: preview.yml (read-only build in the PR's own context), preview-deploy.yml (privileged deploy from a workflow_run completion, base-repo context), check-equation-renders.yml (headless-browser MathJax check on the same artifact), and cleanup-pr-previews.yml (scheduled housekeeping that removes closed PRs' preview directories — this repo's current bespoke workflow never cleans those up).

Why the build/deploy split matters here

gha's README calls this a deliberate trust boundary: untrusted fork code only runs in the read-only build half, and the privileged gh-pages push happens separately in base-repo context. This repo's current single-job preview.yml runs render and deploy together in the PR's own context, which is exactly the shape that doesn't work for fork PRs (see #90) — rossjrw/pr-preview-action's own docs already note the fork-token limitation this repo's preview.yml comment references.

What to do

1. Read gha's README "PR previews (preview family)" section in full: it's 4 cooperating workflows and the workflow_run wiring (the deploy/equation-check stubs' workflows: value must match the build stub's name: exactly).
2. Diff this repo's current preview.yml step-by-step against preview.yml@v2: confirm the source-dir: ./docs/ output path, tinytex: true, and the existing "listing references a missing file" render-failure check all have equivalents (or decide they're no longer needed).
3. Install all four stubs from gha's examples/, not just the build half.
4. Since workflow_run/schedule triggers only fire from the default-branch copy, this migration doesn't take effect until merged to main — plan the PR accordingly (a preview of the preview workflow itself won't demonstrate the new behavior).

Scope

Filed as a tracking issue only, not implementing yet. Related to #90 (fork-PR previews may specifically benefit from the trust-boundary split) but not a duplicate — that issue is about the Claude review path, this one is about the preview build/deploy path.

[d-morrison]

Working on this --- paws off until I'm done.

[d-morrison]

Verdict: held. Two hard blockers upstream, both filed; the migration is a real win once they land

Worked through the step-by-step diff this issue asks for, against preview.yml@v2, preview-deploy.yml@v2, check-equation-renders.yml@v2, cleanup-pr-previews.yml@v2 and the preview@v2 composite. The trust-boundary argument in this issue is correct and the family is genuinely better than what is here. It cannot ship yet.

Blocker 1: preview.yml has no output-dir input, and would publish the 2024 site

The render step passes no --output-dir, so Quarto honours _quarto.yml (output-dir: docs). The staging step then reads from a hardcoded _site:

# preview/action.yml
- name: Render html
  run: quarto render "$PROJECT_PATH" --profile "$RENDER_PROFILE" --to html --no-clean
- name: Stage site for upload
  run: |
    mkdir -p _preview_upload/site/
    cp -r "$PROJECT_PATH/_site/." _preview_upload/site/

It reads a directory the render never wrote to. Normally that fails loudly at ls _site/. It will not fail here, because this repo has a stale _site/ committed to main:

$ git ls-files _site | wc -l
28
$ git log -1 --format='%h %ci' -- _site
a8eb6c8 2024-12-11 20:34:18 -0800

So the build goes green, the artifact holds the December-2024 site, the deploy publishes it, and the PR gets a preview link to a plausible-looking site that never reflects the PR. Reproduced end-to-end with Quarto 1.9.36 against a copy of this repo's config; with _site/ absent the step exits 1, with it present the step exits 0 and stages stale HTML.

Filed upstream as Morrison-Lab/gha#608. Filed the committed-_site/ half separately as #114, since it is worth fixing here regardless --- it is what turns a loud failure into a silent one.

Blocker 2: the preview link would 404

preview-deploy.yml passes no pages-base-url, so rossjrw/pr-preview-action guesses it. The guess has a root-site branch but compares raw strings case-sensitively:

if [ "$name" = "${org}.github.io" ]; then echo "${org}.github.io"
else echo "${org}.github.io/${name}"; fi

This repo is owner UCD-SERG, name ucd-serg.github.io. The casing does not match, so it takes the else branch:

https://UCD-SERG.github.io/ucd-serg.github.io/pr-preview/pr-42/   <- 404
https://ucd-serg.github.io/pr-preview/pr-42/                      <- correct

The deployment is fine (the target folder comes from the preview path, not the URL); only the commented link breaks. Independent evidence the guess was already known wrong here: this repo's current workflow passes pages-base-url: ucd-serg.github.io explicitly.

Filed upstream as Morrison-Lab/gha#609, proposing a passthrough input.

Blocker 3 (shared with #103): no render-log guard

The doesn't match any files or folders listing check has no equivalent anywhere in gha. Details and the upstream issue are on #103; filed as Morrison-Lab/gha#610.

What the migration gets right, so this is worth returning to

Verified from source, not assumed:

• Fork PRs genuinely work. The build half runs pull_request with contents: read in the fork's context; the deploy half runs workflow_run with write in base-repo context. PR-number attribution is handled properly --- workflow_run has no pull_request.number, so the build writes it into the artifact (_preview_upload/meta/pr-number.txt) and the deploy passes it to rossjrw explicitly, overriding the wrong-under-workflow_run default. This is a real gain: the current workflow skips forks outright.
• Removal-on-close survives, and is cheaper. Every heavy step is gated if: github.event.action != 'closed', while the metadata step is deliberately unguarded and writes action=remove. So gha does not re-render the whole site before removing, which the current workflow does.
• render-profile would finally activate _quarto-preview.yml. The input passes --profile "$RENDER_PROFILE". Verified: --profile preview produces the noindex meta tag, no profile does not. That file exists in this repo and is dead today --- the current workflow never selects it, so PR previews are search-indexed.

One thing to adopt now, independently

cleanup-pr-previews.yml needs neither blocker resolved, and this repo has evidence it is needed:

$ gh api "repos/UCD-SERG/ucd-serg.github.io/contents/pr-preview?ref=gh-pages" --jq '.[].name'
pr-107  pr-108  pr-110  pr-111  pr-42  pr-65  pr-76

pr-42 closed 2026-01-10; pr-65 merged 2026-05-12. Both are same-repo (not forks), and both had closed wired into the current workflow --- so the event-based removal demonstrably does not always fire. I did not establish why. A plausible cause is that the current workflow renders before removing, so a render failure blocks the removal, but that is a hypothesis, not a verified finding.

Adopting the cleanup cron alone is a small, safe, independent change. Worth a separate PR rather than folding into this issue.

Recommendation

Hold. Revisit when gha#608 and gha#609 land. Land #114 (the committed _site/) now regardless, and consider the cleanup cron as a standalone change.

One caller-side note for whoever picks this up: add labeled to the types: list. The family's preview:pdf / preview:docx / preview:revealjs / freezer-clear labels are inert without it. And do not copy the example's paths: filter --- this repo has none today, its source surface is effectively the whole tree (*.qmd, people/, papers/, software/, opportunities/, _ejs/, figures/, publications.bib, publications.yml, styles.css, R/), and a paths: miss on a closed event would suppress the removal signal.

[d-morrison]

Split the cleanup-cron half out as #115, since it depends on neither of the two upstream blockers holding this issue (Morrison-Lab/gha#608, #609) and can land on its own.