Read the Docs Now Hosts Docs That Teams Build in Their Own CI
Read the Docs' new direct upload beta lets teams build docs in GitHub Actions or any CI and upload the HTML, keeping versions, previews and search.

Read the Docs will now host documentation that teams build somewhere else, the company said in a Nov. 16 blog post. The feature, called direct upload, takes finished HTML from GitHub Actions, another CI service or a laptop and serves it with the platform’s versions, pull request previews, search, addons, custom domains and offline formats. It is in beta on Read the Docs Community and Read the Docs Business.
One Workflow Step Does the Upload
A new GitHub Action, readthedocs/upload-action@v1, runs after the step that builds the docs and needs only a token and the path to the HTML folder, according to the post by Manuel Kaufmann. The action reads the workflow event to pick the version: a push to main updates the main version, a new tag creates a version and a pull request gets a preview with a link posted in the pull request.
Teams can also attach a PDF, an EPUB or a zipped HTML file. Outside GitHub Actions, a command-line client, readthedocs-upload, does the same job. It needs Python 3.10 or newer, the direct upload guide says, and on other CI services the version name, type and commit have to be passed by hand.
Why Read the Docs Built It
Read the Docs has always built the docs it hosts, and the company said that build step gets in the way of projects with needs it doesn’t cover. In the post it said it heard from teams that use tools its builders don’t support, that need internal services or secrets during a build, or that want one CI run to cover tests and docs.
Uploading a Version Takes It Out of the Build Queue
Once a version has been uploaded, Read the Docs stops building it, the direct upload guide says. Pushes, new commits on a pull request and manual builds no longer trigger anything for that version, so every later update has to come through an upload. Unchecking “Uploaded” in the version settings deletes the uploaded files and starts a normal build again.
Projects that use only direct upload work differently. Read the Docs creates no versions from the repository and no latest or stable aliases; teams upload those names themselves. The first branch or tag uploaded becomes the default version. Deactivating an uploaded version deletes it, and automation rules do not run.
Limits and the Fork Gap
Each upload can be up to 1 GB, has to finish within 30 minutes and counts against a cap of 50 uploads in progress per project, according to the guide. Pull requests from forks cannot upload previews, because GitHub does not give those workflows the repository’s secrets. The guide warns against working around that with pull_request_target, which would run the pull request’s code with access to the token.
New projects can be created with direct upload on and the Read the Docs builders off. Existing projects have to ask support to turn it on.
Key Takeaways
- Read the Docs now hosts docs built in any CI, through a GitHub Action or the
readthedocs-uploadCLI. - Uploaded docs keep versions, pull request previews, search, custom domains and offline formats.
- An uploaded version is never built by Read the Docs again until “Uploaded” is unchecked.
- Uploads are capped at 1 GB and 30 minutes, and forked pull requests get no previews.
The Take
We think hosting is now a product of its own at Read the Docs. The platform started as a build service that also hosted. Now a team whose build needs secrets, internal services or tools the builders lack can still get the versions, previews and search.
Forked pull requests lose out. Outside contributors to open-source projects usually work from forks, and Read the Docs’ own builders give those pull requests previews. Direct upload can’t, because the token must not reach a stranger’s code. We think that is the right security call. It still costs reviewers the preview they used to check a contributor’s change.
So we’d start with one version, not the whole project. Upload main from CI, leave tags and pull requests on the regular builders, and check that the preview links still appear before moving anything else.


