For version control behavior—which branches and tags are built, which version is default, and which versions are active—use the Read the Docs dashboard. For reproducible build behavior—OS, Python version, dependencies, Sphinx or MkDocs commands, output formats—use a repository configuration file, normally .readthedocs.yaml or .readthedocs.yml. A file named .readthedocs.cfg is not the standard Read the Docs configuration filename; unless your project has a custom integration that reads it, treat it as likely ignored.
So for a project targeting a specific stable branch across multiple environments with automated VCS triggers, the dashboard is the source of truth for version activation and default version. The config file does not override dashboard version activation. The dashboard can also disable or hide a version that the repository config would otherwise build. Mixing the two creates two layers: dashboard operational state and repository build state. That can be consistent, but only if you know which layer owns which decision.
What each layer controls
| Layer | Typical control | Version-controlled? |
|---|
| Dashboard | Active branches and tags, default version, hidden versions, some advanced project settings | No, operational state |
| .readthedocs.yaml | Build environment, dependencies, commands, formats, submodules | Yes, in repository |
| .readthedocs.cfg | Not standard; likely ignored unless custom | Yes, but not authoritative |
Webhook-triggered builds
When a webhook triggers a build, the dashboard version settings decide whether that branch or tag is an active version and whether it is the default. The configuration file is then read during the build to set up the environment. Therefore, a config file cannot force a branch to build if the dashboard has not activated it. Conversely, a dashboard change can alter build behavior without any commit, which is the auditability trade-off in the question.
Verification steps
- Inspect the repository root for the exact filename:
find . -maxdepth 1 -name '.readthedocs*' -print
git ls-files '.readthedocs*'
- Open the project dashboard and review the versions page and advanced settings. Note which versions are active, hidden, and default.
- Trigger a build from a webhook or manually. In the build log, check which configuration file, if any, Read the Docs reports as detected. If
.readthedocs.cfg is never mentioned, do not rely on it.
- Run two controlled tests: change a dashboard version setting and rebuild; change a build setting in
.readthedocs.yaml and rebuild. Observe which layer changes which outcome.
Recommendation and uncertainty
Use the dashboard for version control and .readthedocs.yaml for build reproducibility. If strict version-controlled infrastructure is required, keep the build config in Git and document that version activation is dashboard-managed. Do not expect .readthedocs.cfg to control branch or tag activation.
This guidance assumes current Read the Docs SaaS behavior and a modern config file. Self-hosted installations, older projects, and provider-specific dashboards may differ. Verify against current official documentation and your own build logs before changing production version settings.
One missing diagnostic changes the recommendation: are you trying to change which branches and tags build, or to change build dependencies and commands? If it is the former, stay in the dashboard. If it is the latter, put it in .readthedocs.yaml.
readthedocs