How to configure pull request builds

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:

  1. Go to your project dashboard

  2. Go to Admin, then Settings

  3. Enable the Build pull requests for this project option

  4. 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 user to 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:

  1. Go to your project dashboard

  2. Go to Admin, then Settings

  3. Select your option in Privacy level of builds from pull requests

  4. 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 an account with your Git provider.

  • Builds from pull requests have the same memory and time limitations as 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 to send Read the Docs pull request events. You’ll need to re-sync your project’s webhook 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 your provider. Follow the directions on to re-sync the webhook, or create a new webhook integration.

You may also notice this behavior if your Read the Docs account is not connected 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 not being updated with your Git provider, then your connected account may have out dated or insufficient permisisons.

Make sure that you have granted access to the Read the Docs OAuth App for your personal or organization GitHub account. You can also try reconnecting your account with your Git provider.

See also