Your project can be configured to build and host documentation for every new pull request. Previewing changes during review makes it easier to catch formatting and display issues before they go live.
- Build on pull request events
- We create and build a new version when a pull request is opened, and rebuild the version whenever a new commit is pushed.
- Build status report
Your project's pull request build status will show as one of your pull request's checks. This status will update as the build is running, and will show a success or failure status when the build completes.
GitHub build status reporting
- Pull request banner
A pull request banner is shown at the top of documentation pages to let readers know that this version isn't the main version for the project.
Note
Warning banners are available only for :doc:`Sphinx projects </intro/getting-started-with-sphinx>` or projects using :doc:`Read the Docs Addons </addons>`.
- DocDiff
DocDiff shows proposed changes by visually highlighting the differences between the current pull request and the latest version of the project's documentation.
Press
dto toggle between DocDiff and normal pull request preview.Note
DocDiff is available only for projects using :doc:`Read the Docs Addons </addons>`.
.. seealso::
:doc:`/guides/pull-requests`
A guide to configuring pull request builds on Read the Docs.
If pull request previews are enabled for your project,
anyone who can open a pull request on your repository will be able to trigger a build of your documentation.
For this reason, pull request previews are served from a different domain than your main documentation
(org.readthedocs.build and com.readthedocs.build).
Builds from pull requests have access to environment variables that are marked as Public only, if you have environment variables with private information, make sure they aren't marked as Public. See :ref:`environment-variables:Environment variables and build process` for more information.
On |com_brand| you can set pull request previews to be private or public, 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. 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.