Environment variables: document special case for PR preview builds

docs/user/reference/environment-variables.rst

@@ -117,6 +117,11 @@ All :doc:`build processes </builds>` have the following environment variables au
     :Example: ``feature/signup``
     :Example: ``update-readme``
 
+    .. note::
+
+       When building pull requests, this variable contains the numeric ID of the pull request,
+       as we don't have access to the branch name.
+
 .. envvar:: READTHEDOCS_GIT_COMMIT_HASH
 
     Git commit hash identifier checked out from the repository URL.

readthedocs/builds/models.py

@@ -338,7 +338,7 @@ def git_identifier(self):
 
         - If the version is latest (machine created), we resolve to the default branch of the project.
         - If the version is stable (machine created), we resolve to the branch that the stable version points to.
-        - If the version is external, we return the identifier, since we don't have access to the name of the branch.
+        - If the version is external, we return the PR identifier, since we don't have access to the name of the branch.
         """
         # Latest is special as it doesn't contain the actual name in verbose_name.
         if self.slug == LATEST and self.machine:
@@ -353,12 +353,6 @@ def git_identifier(self):
                 return original_stable.verbose_name.removeprefix("origin/")
             return self.identifier.removeprefix("origin/")
 
-        if self.type == EXTERNAL:
-            # If this version is a EXTERNAL version, the identifier will
-            # contain the actual commit hash. which we can use to
-            # generate url for a given file name
-            return self.identifier
-
         # For all other cases, verbose_name contains the actual name of the branch/tag.
         return self.verbose_name
 

readthedocs/rtd_tests/tests/test_version.py

@@ -102,7 +102,7 @@ def test_git_identifier_for_latest_version(self):
 
     def test_git_identifier_for_external_version(self):
         self.assertEqual(
-            self.external_version.git_identifier, self.external_version.identifier
+            self.external_version.git_identifier, self.external_version.verbose_name
         )
 
     @override_settings(

readthedocs/rtd_tests/tests/test_version_commit_name.py

@@ -134,4 +134,4 @@ def test_external_version(self):
             verbose_name="11",
             type=EXTERNAL,
         )
-        self.assertEqual(version.git_identifier, identifier)
+        self.assertEqual(version.git_identifier, "11")