Build failures after automatic ReadTheDocs build image upgrade

Context

ReadTheDocs periodically upgrades the default Docker build images (for example, moving from ubuntu-20.04 to ubuntu-22.04). Projects that do not explicitly pin build.image in .readthedocs.yaml receive the new image automatically on the next build.

Problem

An automatic image upgrade can introduce missing system packages, changed Python versions, or altered dependency resolution that breaks previously successful builds. The platform provides no per-project rollback button; recovery requires a configuration commit that sets build.image back to a known-good tag and a new build trigger.

Open questions

Documentation describes pinning as the mitigation, but it does not clarify whether a project can permanently opt out of future automatic image upgrades without maintaining an explicit pin, nor how deprecation timelines for older images are communicated to project maintainers.

• Is there a supported mechanism to disable automatic build image upgrades for a project without manually pinning build.image?
• How does ReadTheDocs notify maintainers when a pinned image is scheduled for deprecation or removal?