Choosing the Best PR Preview Deployment Strategy – Netlify vs CircleCI

[AR21SM]

Hi everyone! 👋

As part of improving the PR review workflow for the DISCOVER-Cookbook, I’ve been exploring the best way to preview documentation changes from pull requests.

Recently, I attempted to implement rossjrw/pr-preview-action but encountered limitations with forked PRs — v2 should fix this, but it’s not released yet.

So, I'm opening this discussion to compare two popular options for deploying PR previews:

---

⚖️ Options Under Consideration

CircleCI – Pros

• Retains artifacts longer, which is great for PR reviews - 30-day retention on free plan, longer on paid plans
• Full build environment control - Complete access to VM with custom Python versions, system packages, and dependencies
• Advanced testing workflows - Native support for tox testing across multiple Python versions and environments
• GitHub Pages integration - Can deploy final builds to GH Pages while using CircleCI for PR previews
• Preferred across several NumFOCUS projects to stick with GH Pages for deployment

CircleCI – Cons

• PR previews from forks still need additional configuration (tokens or redirects)
• No native public preview URL unless combined with Netlify or GH Pages + redirect
• Higher maintenance overhead - More configuration files and setup complexity
• Manual preview link generation - Need custom scripts to generate and share preview URLs
• Slightly more complex to configure and manage secrets for fork compatibility

---

Netlify – Pros

• Zero-configuration PR previews - Automatic preview URLs for every pull request out of the box
• Fork-friendly - Handles external contributor PRs without additional security setup
• Clean preview links per PR – automatically generated and easy to share
• Generous free tier - 100GB bandwidth and 300 build minutes per month for personal projects
• Best for static HTML-only sites where build control is not critical

Netlify – Cons

• Limited control over build steps (eg tox, custom sphinx plugins)
• Artifact retention is shorter; previews disappear with time or inactivity

Summary

Priority	CircleCI	Netlify
Fork PR support	Requires setup	Native
Build complexity	Full control	Limited
Setup simplicity	Complex	Simple
Testing workflows	Excellent	Basic
Preview URLs	Manual setup	Automatic

---

Looking forward to your thoughts!
Thanks 🙏

— @AR21SM

[AR21SM]

Hi @aterrel, @OriolAbril, @melissawm , @kamila-NF ,@emmasaroyan

To help resolve Issue #80, I’ve shared a post comparing Netlify and CircleCI for PR previews, including pros and cons, a summary table, and a quick poll.

Could you please take a look and share your thoughts? Would really appreciate your input to decide the best direction forward

[aterrel]

I don't want to maintain configurations for fork so Netlify seems the most appropriate.