GitHub Pages PR Previews
I’ve been using Cursor Cloud Agents to develop this site, which means I’m often reviewing changes in PRs (pull requests) from my phone. The missing piece in my workflow was a way for each PR to have a live preview link so I could test changed and merge with confidence. I’ve now set this up using GitHub actions.
What I wanted
The goal was to keep things simple:
- Keep normal deploys to
mainexactly as they are - Generate a preview URL for each pull request
- Clean up preview files automatically when the PR is closed
How it works
I split things into two GitHub Actions workflows. The first workflow handles the normal site deploy to the special gh-pages deployment branch on pushes to the main branch.
The second workflow runs on pull request events (opened, reopened, synchronize, and closed). For open PRs, it builds Jekyll with a PR-specific base URL like https://petegraham.com/pr-preview/pr-13/.
That base URL is important so CSS, links, and assets resolve correctly under the preview path.After building, the workflow deploys _site on the gh-pages branch into a subdirectory for the PR:
gh-pages/pr-preview/pr-<PR_NUMBER>/
When the PR is closed, the same workflow removes that preview directory.
The one detail that saves headaches
My main deploy workflow now excludes the preview umbrella directory from clean-up (clean-exclude: pr-preview). Without that, a regular deploy to main can wipe all preview sites.
So the setup works because the two workflows cooperate:
- main deploy publishes the production site
- PR deploy publishes preview folders
- preview folders are preserved until a PR is closed
One-time GitHub settings
I also had to make sure repository settings matched the workflow expectations:
- GitHub Pages source set to
gh-pages(root) - Actions workflow permissions set to read and write
Without write permissions, the preview action can’t publish to gh-pages or comment preview links on pull requests.
Result
Now each pull request gets a working preview URL in the PR conversation, and I can review content/layout changes before merging. It’s a small change, but it makes this mobile first development process feel much easier.
If you'd like to contact me then you can email writing@petegraham.co.uk.