Choosing Between Read the Docs Community and Business Tiers

The decision: match repository visibility to the tier

You need to host documentation for a project, but you are not sure whether Read the Docs' free community service is appropriate or whether you should pay for the business offering. The practical takeaway is simple: use the community tier for public, open-source repositories, and use the business tier when the repository is private, when you need single sign-on, or when you require custom domains and commercial support. Do not use the community tier for repositories that contain secrets, internal API references, or regulated data, because community builds are public.

Constraints to check before connecting a repository

• Repository visibility: public or private in GitHub, GitLab, or Bitbucket.
• Compliance: whether the documentation contains credentials, internal endpoints, or regulated information.
• Authentication: whether readers need SAML or OIDC single sign-on.
• Branding: whether you need a custom domain instead of a readthedocs.io subdomain.
• Support: whether your team can rely on community help or needs priority support and a commercial agreement.
• Build scale: whether a large monorepo with many branches and tags might approach builder concurrency or timeout limits.

Supported options compared

Factor	Community (free)	Business (paid)
Repository visibility	Public repositories only	Public and private repositories
Source providers	GitHub, GitLab, Bitbucket	GitHub, GitLab, Bitbucket
Build triggers	Automatic on push, branches, and tags	Automatic on push, branches, and tags
Versioned builds	Branches and tags appear in the version switcher	Branches and tags appear in the version switcher
Authentication	Public read access	SAML or OIDC single sign-on with access control
Custom domains	Not supported	Supported
Support and terms	Community support; no guaranteed service level	Priority support; commercial terms
Build configuration	.readthedocs.yaml at repository root	.readthedocs.yaml at repository root

Plan names, feature limits, and pricing change over time. Confirm the current tier boundaries in your Read the Docs dashboard before you base architecture on this comparison.

Trade-offs

Community tier

The community tier is free and supports automatic builds from public GitHub, GitLab, and Bitbucket repositories. It handles versioned builds from branches and tags, and it can aggregate subprojects. The trade-off is that everything built is public, there is no guaranteed service-level agreement, and support is limited to community channels. If a contributor accidentally pushes an internal hostname or a secret to a documentation file, that information becomes publicly visible.

Business tier

The business tier adds private repository support, SAML or OIDC single sign-on, custom domains, priority support, and commercial terms. The trade-off is cost, plus operational work for custom domains: you must configure DNS and manage certificates. Test a custom domain on a staging subdomain before pointing production traffic at it.

Implementation: add build configuration and connect the repository

Both tiers read the same build configuration file, so the implementation is similar regardless of tier. The difference is which repository visibility and dashboard plan you select.

1. Create .readthedocs.yaml

Create this file at the root of your documentation repository. Adjust the Python version, requirements path, and Sphinx configuration path to match your project.

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: \"3.11\"
sphinx:
  configuration: docs/conf.py
python:
  install:
    - requirements: docs/requirements.txt

Where to run: in a local clone of the repository, then push the commit to your source-control provider.

Required permissions: write access to the repository, and a Read the Docs account allowed to connect projects.

Placeholders: replace docs/conf.py and docs/requirements.txt with your actual paths.

Expected check: after pushing, the Read the Docs project build page shows a new build for the branch or tag.

Risk: pushing directly to the default branch can start a build immediately. Create a feature branch first, verify the configuration, then merge.

2. Connect the repository in the dashboard

1. Log in to Read the Docs and import your project from GitHub, GitLab, or Bitbucket.
2. Select the repository and grant the Read the Docs application the permissions it requests.
3. Confirm the repository visibility matches the tier you chose: public for community, public or private for business.
4. Check the source-control repository webhook settings. Read the Docs usually configures the webhook automatically, but verify that push events are enabled.

3. Trigger and check a build

1. Push a documentation-only commit or create a tag, for example v1.0.0.
2. Open the project builds page in Read the Docs and confirm the build starts automatically through the webhook.
3. When the build finishes, open the built version URL, such as https://<project>.readthedocs.io/en/<version>/.
4. Confirm the version switcher lists the expected branch or tag and that static asset links resolve.

Validation and rollback

Validation checks

• Verify repository visibility in your source-control provider matches the chosen Read the Docs tier before enabling the integration.
• Push a documentation-only commit and confirm the build starts automatically through the repository webhook.
• Open the built version URL and confirm the version selector lists the expected branch or tag.
• Review the current Read the Docs plan comparison page in the product dashboard to confirm feature availability and pricing.

Rollback

Because adding .readthedocs.yaml and connecting a project changes repository and service state, rollback means removing both. Revert the commit that added the configuration file, then deactivate or delete the project in the Read the Docs dashboard and remove the webhook from your source repository if it was added manually. Deleting a project removes its build history, so only do this when you no longer need the documentation.

Limitations

• Community builds are public. Do not use this tier for secrets, internal APIs, or regulated data.
• Build timeouts and concurrency limits differ by tier. Large monorepos with many documentation versions may hit builder limits.
• Custom domains require DNS configuration and certificate management. Test in a staging subdomain before cutting over production traffic.
• Plan features and limits change. Verify current boundaries before committing to a tier.

After you connect the repository, open the project builds page and confirm that the most recent build for your branch or tag shows a passed status. If the build fails, inspect the build log for missing dependencies or an incorrect Sphinx configuration path before pushing further changes.