Read the Docs pull request previews and the project visibility boundary

Question

Read the Docs can build documentation for pull requests so reviewers can inspect rendered changes before a merge. The unresolved point is how those preview builds relate to the project's visibility setting: whether the preview URL inherits the project's public or private state, or is reachable by anyone holding the link.

Visibility is configured at the project level, but individual versions — branches, tags, and pull request builds — are managed separately and can be active or inactive, public or private, on their own. On the community site (readthedocs.org), private project support has historically been limited and imported repositories default to public visibility, while the commercial platform (readthedocs.com) gates private docs behind authenticated access such as organization or team membership. Because of that split, the default exposure of a pull request preview build is not obvious from the main visibility setting, and the exact behavior may vary by platform and plan.

Questions to resolve:

Do pull request preview builds inherit the parent project's visibility, or are they served as link-public URLs by default?
Where is per-version privacy configured so an active pull request version matches the intended project-level boundary?
How does this behavior differ between readthedocs.org and readthedocs.com, and has it changed in recent releases?

Tasadduq Burney · Answer

AnswerOn readthedocs.org pull‑request preview builds are always publicly reachable via their unique URL, regardless of the project’s visibility setting, because the free community site does not support private projects.On readthedocs.com a pull‑request preview inherits the project’s visibility by default, but its visibility can be overridden per‑version in the Versions admin page. If the project is marked private, the PR preview is private unless explicitly set to public.Confirmed factsPer‑version privacy is configured under Project → Admin → Versions. Each version (branch, tag, or external PR) shows a lock icon that toggles public/private state.Recent RTD releases (v2.0+) added a project‑level setting "Default visibility for external versions" that lets you choose whether newly created PR previews start as public or private on .com.Likely explanation & platform differencesInheritance vs. link‑public: On .org PR previews are link‑public by default; on .com they follow the project’s visibility unless the per‑version lock is changed or the "Default visibility for external versions" setting overrides it.Where to configure: Use the Versions page to set the lock for the specific external PR version; this ensures the preview matches the intended project‑level boundary.Behavior change: Earlier versions of .com always served PR previews publicly unless manually made private. The v2.0+ default‑visibility setting now allows PR previews to be private by default, aligning them with the project’s setting.Verification stepsLink a test repository to both readthedocs.org and readthedocs.com and enable pull‑request builds.Open a PR and note the preview URL.On each platform go to Project → Admin → Versions, locate the external PR version, and observe its lock state.Toggle the lock (public ↔ private) and attempt to access the preview URL in an incognito window (no login) to confirm accessibility.Check the project’s "Default visibility for external versions" setting to see how it affects newly created PR previews without manual adjustment.Missing diagnostic detail that could change the recommendation: Are you on a paid (Team/Business/Enterprise) plan on readthedocs.com? Enterprise plans can enforce additional restrictions such as IP allowlists or SSO gating that override version visibility.

Read the Docs pull request previews and the project visibility boundary

1 answer

Answer

Confirmed facts

Likely explanation & platform differences

Verification steps

Your perspective belongs here.

0 question comments