Build: expose VCS-related environment variables

Introduce 3 new variables: * `READTHEDOCS_REPOSITORY_URL` * `READTHEDOCS_REPOSITORY_IDENTIFIER` * `READTHEDOCS_REPOSITORY_IDENTIFIER_HASH` Closes #9423
readthedocs · Mar 21, 2023 · 3114f95 · 3114f95
1 parent 4687f09
commit 3114f95
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 0 deletions.
diff --git a/docs/user/reference/environment-variables.rst b/docs/user/reference/environment-variables.rst
@@ -56,6 +56,31 @@ All :doc:`build processes </builds>` have the following environment variables au
     :Example: ``https://docs.readthedocs.io/ja/stable/``
     :Example: ``https://example--17.org.readthedocs.build/fr/17/``
 
+.. envvar:: READTHEDOCS_REPOSITORY_URL
+
+    URL from where the source code to generate the documentation is clonned.
+    It could be HTTPS, SSH or any other URL scheme supported by Git.
+    This is the same URL defined under :guilabel:`Admin` > :guilabel:`Settings` > :guilabel:`Repository URL`.
+
+    :Example: ``https://github.com/readthedocs/readthedocs.org``
+    :Example: ``git@github.com:readthedocs/readthedocs.org.git``
+
+.. envvar:: READTHEDOCS_REPOSITORY_IDENTIFIER
+
+    Git identifier checked out from the repository URL.
+    It could be a branch or tag name.
+
+    :Example: ``v1.x``
+    :Example: ``bugfix/docs-typo``
+    :Example: ``feature/signup``
+    :Example: ``update-readme``
+
+.. envvar:: READTHEDOCS_REPOSITORY_IDENTIFIER_HASH
+
+    Git commit hash identifier checked out from the repository URL.
+
+    :Example: ``1f94e04b7f596c309b7efab4e7630ed78e85a1f1``
+
 .. seealso::
 
    :doc:`/environment-variables`

diff --git a/readthedocs/doc_builder/director.py b/readthedocs/doc_builder/director.py
@@ -574,6 +574,9 @@ def get_rtd_env_vars(self):
             "READTHEDOCS_OUTPUT": os.path.join(
                 self.data.project.checkout_path(self.data.version.slug), "_readthedocs/"
             ),
+            "READTHEDOCS_REPOSITORY_URL": self.data.project.repo,
+            "READTHEDOCS_REPOSITORY_IDENTIFIER": self.data.version.identifier,
+            "READTHEDOCS_REPOSITORY_IDENTIFIER_HASH": self.data.build["commit"],
         }
         return env
 

diff --git a/readthedocs/projects/tests/test_build_tasks.py b/readthedocs/projects/tests/test_build_tasks.py
@@ -279,6 +279,9 @@ def test_get_env_vars(self, load_yaml_config, build_environment, config, externa
             "READTHEDOCS_OUTPUT": os.path.join(
                 self.project.checkout_path(self.version.slug), "_readthedocs/"
             ),
+            "READTHEDOCS_REPOSITORY_URL": self.project.repo,
+            "READTHEDOCS_REPOSITORY_IDENTIFIER": self.version.identifier,
+            "READTHEDOCS_REPOSITORY_IDENTIFIER_HASH": self.build.commit,
         }
 
         self._trigger_update_docs_task()