Add reusable preview/publish workflow family

[d-morrison]

Summary

Centralize the PR-preview / publish workflow family into d-morrison/gha as a reusable workflow_call workflow (+ composite action), so consumer repos call a thin stub instead of carrying their own copy.

This is already flagged as a future scope item in the gha README:

This is the pilot set (the byte-identical / near-identical workflow families). Additional families (spell check, lint-changed-files, pr-commands, R-CMD-check, publish/preview) may be added later.

Motivation

d-morrison/rme currently carries the preview pipeline as three fully-inlined local workflows:

• .github/workflows/preview.yml — build (checkout, Quarto/R/renv setup, apt deps, render, artifact upload)
• .github/workflows/preview-deploy.yml — deploy to gh-pages via workflow_run (base-repo context)
• .github/workflows/cleanup-pr-previews.yml — cleanup

Because this logic lives only in rme, fixes have to be made by hand in the local copy. A recent example: d-morrison/rme#913 — preview deploys were silently skipped because PR metadata was written before actions/checkout ran git clean -ffdx, wiping it from the artifact. That class of bug would be fixed once, centrally, if the family lived here.

Scope / design notes

• Mirror the existing two-layer pattern in this repo: composite action (preview/action.yml) + reusable workflow (.github/workflows/preview.yml, on: workflow_call), consumers pin @v1.
• Preserve the load-bearing pieces of rme's current setup:
  • Split build/deploy trust boundary — build runs read-only in the (possibly fork) PR context; deploy runs in the base-repo context via workflow_run. Don't collapse these into one privileged job.
  • git clean ordering — write PR metadata after checkout (the #913 fix).
  • Concurrency with cancel-in-progress: true (see rme issue #812).
  • Label-gated render variants (preview:pdf / preview:docx / preview:revealjs, clear freezer freeze-bypass).
  • Quarto freeze cache restore/save keyed on renv.lock + head SHA.
• Parameterize the R-package/Quarto specifics as inputs (apt packages, R version, submodules, renv on/off, render profile/targets) so non-rme consumers can reuse it.
• Document required caller permissions: and add a caller stub under examples/.
• Update the README "Available reusable workflows" table and REVDEPS.md once rme migrates.

Follow-up

Once the reusable workflow lands here and is tagged into @v1, open a companion PR in d-morrison/rme to replace its three local preview workflows with caller stubs.

References

• rme local workflows: preview.yml, preview-deploy.yml, cleanup-pr-previews.yml
• Bug that motivated this: d-morrison/rme#913
• gha README → "Scope" (publish/preview listed as a later family)