Build: expose VCS-related environment variables

docs/user/canonical-urls.rst

@@ -34,7 +34,7 @@ The canonical URL takes the following into account:
 
 * The default version of your project (usually "latest" or "stable").
 * The canonical :doc:`custom domain </custom-domains>` if you have one,
-  otherwise the default :ref:`subdomain <default_subdomain>` will be used.
+  otherwise the default :ref:`subdomain <default-subdomain>` will be used.
 
 For example, if you have a project named ``example-docs``
 with a custom domain ``https://docs.example.com``,

docs/user/custom-domains.rst

@@ -5,7 +5,7 @@ You can serve your documentation project from your own domain,
 for instance ``docs.example.com``.
 This is great for maintaining a consistent brand for your product and its documentation.
 
-.. _default_subdomain:
+.. _default-subdomain:
 
 .. rubric:: Default subdomains
 

docs/user/reference/environment-variables.rst

@@ -44,6 +44,43 @@ All :doc:`build processes </builds>` have the following environment variables au
 
     :Example: ``/home/docs/checkouts/readthedocs.org/user_builds/project/envs/version``
 
+.. envvar:: READTHEDOCS_CANONICAL_URL
+
+    Canonical base URL for the version that is built.
+    If the project has configured a :doc:`custom domain </custom-domains>` (e.g. ``docs.example.com``) it will be used in the resulting canonical URL.
+    Otherwise, your project's :ref:`default subdomain <default-subdomain>` will be used.
+
+    The path for the language and version is appended to the domain, so the final canonical base URLs can look like the following examples:
+
+    :Example: ``https://docs.example.com/en/latest/``
+    :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: ``[email protected]: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`

readthedocs/api/v2/serializers.py

@@ -5,6 +5,7 @@
 from rest_framework import serializers
 
 from readthedocs.api.v2.utils import normalize_build_command
+from readthedocs.builds.constants import EXTERNAL
 from readthedocs.builds.models import Build, BuildCommandResult, Version
 from readthedocs.oauth.models import RemoteOrganization, RemoteRepository
 from readthedocs.projects.models import Domain, Project
@@ -124,11 +125,20 @@ class VersionAdminSerializer(VersionSerializer):
     """Version serializer that returns admin project data."""
 
     project = ProjectAdminSerializer()
+    canonical_url = serializers.SerializerMethodField()
     build_data = serializers.JSONField(required=False, write_only=True)
 
+    def get_canonical_url(self, obj):
+        return obj.project.get_docs_url(
+            lang_slug=obj.project.language,
+            version_slug=obj.slug,
+            external=obj.type == EXTERNAL,
+        )
+
     class Meta(VersionSerializer.Meta):
         fields = VersionSerializer.Meta.fields + [
             "build_data",
+            "canonical_url",
         ]
 
 

readthedocs/builds/models.py

@@ -601,7 +601,8 @@ class Meta:
         proxy = True
 
     def __init__(self, *args, **kwargs):
-        self.project = APIProject(**kwargs.pop('project', {}))
+        self.project = APIProject(**kwargs.pop("project", {}))
+        self.canonical_url = kwargs.pop("canonical_url", None)
         # These fields only exist on the API return, not on the model, so we'll
         # remove them to avoid throwing exceptions due to unexpected fields
         for key in ['resource_uri', 'absolute_url', 'downloads']:

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
 
@@ -615,6 +618,12 @@ def get_build_env_vars(self):
                 }
             )
 
+        env.update(
+            {
+                "READTHEDOCS_CANONICAL_URL": self.data.version.canonical_url,
+            }
+        )
+
         # Update environment from Project's specific environment variables,
         # avoiding to expose private environment variables
         # if the version is external (i.e. a PR build).

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()
@@ -301,6 +304,11 @@ def test_get_env_vars(self, load_yaml_config, build_environment, config, externa
             # Local and Circle are different values.
             # We only check it's present, but not its value.
             READTHEDOCS_VIRTUALENV_PATH=mock.ANY,
+            READTHEDOCS_CANONICAL_URL=self.project.get_docs_url(
+                lang_slug=self.project.language,
+                version_slug=self.version.slug,
+                external=external,
+            ),
         )
         if not external:
             expected_build_env_vars["PRIVATE_TOKEN"] = "a1b2c3"

readthedocs/rtd_tests/tests/test_api.py

@@ -2442,6 +2442,7 @@ def test_get_version_by_id(self):
             "built": False,
             "id": 18,
             "active": True,
+            "canonical_url": "http://readthedocs.org/docs/pip/en/0.8/",
             "project": {
                 "analytics_code": None,
                 "analytics_disabled": False,