preview-deploy.yml

The deploy half of the PR-preview family. Triggered on the build workflow’s workflow_run completion, it downloads the artifact and publishes the preview to gh-pages in the base-repo context, then comments the preview link. Keeping it split from the read-only build half is the trust boundary, so untrusted fork code never holds write permissions. The deploy stub’s on: workflow_run: workflows: value must match the build workflow’s name:.

Inputs

Input	Type	Default	Description
pages-base-url	string	''	Custom Pages base URL (e.g. 'org.github.io' or a custom domain) to override automatic URL guessing by pr-preview-action.
pages-base-path	string	''	Custom Pages base path prefix to override automatic path guessing by pr-preview-action.

Partial adoption and artifact contract

Repositories with custom build sequences (e.g. bespoke multi-stage rendering, custom post-render highlighting, or multi-step assets) do not need to use preview.yml or preview/action.yml to benefit from the deploy and cleanup machinery. They can run a custom build workflow that uploads the standard three-file pr-preview-site artifact, and hand off directly to preview-deploy.yml and cleanup-pr-previews.yml.

The artifact named pr-preview-site must contain:

• site/ — Directory containing the rendered HTML/site files to publish to gh-pages.
• meta/pr-number.txt — Text file containing the pull request number (e.g. 123).
• meta/action.txt — Text file containing either deploy (to deploy or update the preview) or remove (when the PR is closed).

preview-deploy.yml downloads this artifact from the triggering workflow_run event, reads meta/pr-number.txt and meta/action.txt, and publishes site/ to gh-pages in the base repository context without running untrusted code.

Permissions

Grant contents: write (push to gh-pages), pull-requests: write (post the preview-link comment), and actions: read (download the build artifact).

Example

# Copy to .github/workflows/preview-deploy.yml in your repo.
# Deploy half of the PR-preview family: triggered when the build workflow
# finishes, downloads its artifact, and publishes the preview to gh-pages. This
# runs in the BASE-repo context, so its token can write --- keeping it separate
# from the read-only build half is the trust boundary.
#
# NOTE: the `workflows:` value below MUST match the `name:` of your build
# workflow (examples/preview.yml). `workflow_run` triggers only fire when this
# file lives on the default branch.
name: Quarto Preview Deploy

on:
  workflow_run:
    workflows: ["Quarto Preview Build"]
    types: [completed]

jobs:
  deploy:
    permissions:
      contents: write # push to gh-pages
      pull-requests: write # post the preview-link comment
      actions: read # download the build artifact
    uses: Morrison-Lab/gha/.github/workflows/preview-deploy.yml@v2
    # with:
    #   pages-base-url: 'example.org' # custom Pages base URL or custom domain
    #   pages-base-path: 'docs'       # custom Pages base path prefix

See examples/preview-deploy.yml for the full caller stub.