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. |
idle-days |
number | 0 |
When greater than 0, also remove the preview of an open pull request whose last update is more than this many days old. The pull request is untouched and its next push rebuilds the preview; until then its earlier preview links return 404. Counts whole days since the PR’s last update (a comment or label counts, not only a push). Must be a non-negative whole number. Keeps a repository with many long-lived open PRs under the 1 GB GitHub Pages artifact cap. Default 0 disables it. |
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
# idle-days: 0 # >0: also remove previews of open PRs idle this many daysSee examples/cleanup-pr-previews.yml for the full caller stub.