cleanup-pr-previews.yml

The housekeeping half of the PR-preview family. On a schedule, it deletes gh-pages preview directories for pull requests that are no longer open.

Inputs

Input	Type	Default	Description
preview-dir	string	'pr-preview'	Directory on gh-pages that holds the per-PR preview subdirectories.
compact-history	boolean	false	Orphan-squash the gh-pages branch to a single commit after pruning, discarding accumulated preview/publish history to reclaim the space deleted snapshots still occupy. Safe for branch-based Pages (what the preview family uses).
publish-workflow	string	''	Workflow name pattern for the base-branch publish/deploy workflow that must succeed before a merged PR preview is removed (e.g. 'Quarto Publish*' or 'Deploy Website'). Matches against the workflow’s declared display name (name:). If a workflow filename (.yml or .yaml) is provided, it is resolved via the GitHub API. Defaults to auto-detecting workflows with 'publish' or 'deploy' in their name. Set to 'none' or 'false' to disable.
wait-for-publish	boolean	true	When true (default), wait until the base branch’s publish/deploy workflow succeeds before removing preview directories for merged PRs. When false, merged PR previews are removed immediately regardless of publish status.
runs-on	string	empty (CI_RUNNER variable, else ubuntu-latest)	Runner label for the job. Use a self-hosted label only for a private repository; never for a public one, whose pull requests can run arbitrary code on it (#1167).

Permissions

Grant contents: write (commit the deletions to gh-pages), pull-requests: read, and actions: read (query workflow runs to ensure merged PR previews are not pruned before deployment).

Example

Do not name a concurrency: group gh-pages anywhere in your caller workflow – neither a top-level block nor one on the calling job, which deadlock identically. Any other group name is fine, and is how you serialize the caller’s own runs. cleanup-pr-previews.yml serializes its gh-pages branch modifications with the deploy workflows on its cleanup job (group: gh-pages). A caller-level block with the same group name deadlocks GitHub Actions against the nested job: cleanup fails with no runner, no steps, and no log. This workflow publishes nothing, so the symptom is not a stale site: the deletions never land, and preview directories for closed PRs accumulate on gh-pages (gha#809).

# Copy to .github/workflows/cleanup-pr-previews.yml in your repo.
# Housekeeping half of the PR-preview family: periodically deletes gh-pages
# preview directories for PRs that are no longer open. The calling job grants
# contents:write so it can commit the deletions back to gh-pages.
name: Clean up PR Previews

on:
  workflow_dispatch:
  schedule:
    - cron: "0 0 * * 0" # Weekly on Sunday at midnight UTC

jobs:
  cleanup:
    permissions:
      contents: write
      pull-requests: read
      actions: read
    uses: Morrison-Lab/gha/.github/workflows/cleanup-pr-previews.yml@v3
    # with:
    #   preview-dir: pr-preview     # gh-pages dir holding the per-PR previews
    #   compact-history: true       # orphan-squash gh-pages to one commit after
    #                               # pruning, so deleted snapshots stop bloating
    #                               # the repo. Branch-based Pages only.
    #   publish-workflow: ''        # base-branch publish workflow name/pattern
    #   wait-for-publish: true      # wait for publish before pruning merged PRs

See examples/cleanup-pr-previews.yml for the full caller stub.