- How-to guides: build process
- How to configure pull request builds
- Edit on GitHub
In this section, you can learn how to configure pull request builds.
To enable pull request builds for your project,your Read the Docs account needs to be connected to an account with a supported Git provider.See Limitations for more information.
If your account is already connected:
Go to your project dashboard
Go to Admin, then Settings
Enable the Build pull requests for this project option
Click on Save
Tip
Pull requests opened before enabling pull request builds will not trigger new builds automatically.Push a new commit to the pull request to trigger its first build.
Privacy levels
Note
Privacy levels are only supported on Business hosting.
If you didn’t import your project manually and your repository is public,the privacy level of pull request previews will be set to Public,otherwise it will be set to Private.Public pull request previews are available to anyone with the link to the preview,while private previews are only available to users with access to the Read the Docs project.
Warning
If you set the privacy level of pull request previews to Private,make sure that only trusted users can open pull requests in your repository.
Setting pull request previews to private on a public repository can allow a malicious userto access read-only APIs using the user’s session that is reading the pull request preview.Similar to GHSA-pw32-ffxw-68rh.
To change the privacy level:
Go to your project dashboard
Go to Admin, then Settings
Select your option in Privacy level of builds from pull requests
Click on Save
Privacy levels work the same way as normal versions.
Limitations
Only available for GitHub and GitLab currently. Bitbucket is not yet supported.
To enable this feature, your Read the Docs account needs to be connected to anaccount with your Git provider.
Builds from pull requests have the same memory and time limitationsas regular builds.
Additional formats like PDF and EPUB aren’t built, to reduce build time.
Search queries will default to the default experience for your tool.This is a feature we plan to add,but don’t want to overwhelm our search indexes used in production.
The built documentation is kept for 90 days after the pull request has been closed or merged.
Troubleshooting
- No new builds are started when I open a pull request
The most common cause is that your repository’s webhook is not configured tosend Read the Docs pull request events. You’ll need to re-sync your project’swebhook integration to reconfigure the Read the Docs webhook.
To resync your project’s webhook, go to your project’s admin dashboard,Integrations, and then select the webhook integration for yourprovider. Follow the directions on to re-sync the webhook, or create a newwebhook integration.
You may also notice this behavior if your Read the Docs account is notconnected to your Git provider account, or if it needs to be reconnected.You can (re)connect your account by going to your <Username dropdown>,Settings, then to Connected Services.
- Build status is not being reported to your Git provider
If opening a pull request does start a new build, but the build status is notbeing updated with your Git provider, then your connected account may have outdated or insufficient permisisons.
Make sure that you have granted access to the Read the Docs OAuth App foryour personal or organization GitHub account. You can also try reconnectingyour account with your Git provider.
