From 3114f95b9af0363e58dcd3195646245015fa8d17 Mon Sep 17 00:00:00 2001
From: Manuel Kaufmann <humitos@gmail.com>
Date: Tue, 21 Mar 2023 13:09:06 +0100
Subject: [PATCH] Build: expose VCS-related environment variables

Introduce 3 new variables:

* `READTHEDOCS_REPOSITORY_URL`
* `READTHEDOCS_REPOSITORY_IDENTIFIER`
* `READTHEDOCS_REPOSITORY_IDENTIFIER_HASH`

Closes #9423
---
 docs/user/reference/environment-variables.rst | 25 +++++++++++++++++++
 readthedocs/doc_builder/director.py           |  3 +++
 .../projects/tests/test_build_tasks.py        |  3 +++
 3 files changed, 31 insertions(+)

diff --git a/docs/user/reference/environment-variables.rst b/docs/user/reference/environment-variables.rst
index 68bbfb532af..49bbc7e35fd 100644
--- 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
index 4d8f3edc3dc..1c8ea6da189 100644
--- 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
index 11b7212d60a..9f053ffd6e5 100644
--- 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()