Builds: support custom Git checkout command (#12412)

Initial POC to support this feature. It will allow us to support
customers with specific needs. We don't plan to expose this directly to
users yet, since there are some internals that need to be met to work:

- Use specific environment variables
- Clone the repository in `.` to keep with the default workflow
- Depending on the repository structure, a custom YAML path and custom
`python.install.requirements` may be needed as well (I added this commit
humitos/rocm-libraries@a393812)

All of this can be documented eventually, but we need an internal way to
write these custom commands to onboard customers with these needs.

<img width="1161" height="518" alt="Screenshot_2025-08-15_12-06-48"
src="https://github.com/user-attachments/assets/b95c5007-5346-4539-883b-58546ee15d4f"
/>

The value for `Project.git_checkout_command` is:

```json
[
    "env",
    "echo $READTHEDOCS_GIT_CLONE_URL",
    "git clone --no-checkout --no-tag --filter=blob:none --depth 1 $READTHEDOCS_GIT_CLONE_URL .",
    "git sparse-checkout init --cone",
    "git sparse-checkout set projects/rocblas",
    "git checkout $READTHEDOCS_GIT_IDENTIFIER"
]
```

Closes #12313

Author: humitos

readthedocs/api/v2/serializers.py

@@ -95,6 +95,7 @@ class Meta(ProjectSerializer.Meta):
             "readthedocs_yaml_path",
             "clone_token",
             "has_ssh_key_with_write_access",
+            "git_checkout_command",
         )
 
 

readthedocs/projects/migrations/0155_custom_git_checkout_step.py

@@ -0,0 +1,30 @@
+# Generated by Django 5.2.4 on 2025-08-15 09:07
+
+from django.db import migrations
+from django.db import models
+from django_safemigrate import Safe
+
+
+class Migration(migrations.Migration):
+    safe = Safe.before_deploy()
+
+    dependencies = [
+        ("projects", "0154_set_latest_build"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="historicalproject",
+            name="git_checkout_command",
+            field=models.JSONField(
+                blank=True, null=True, verbose_name="Custom command to execute before Git checkout"
+            ),
+        ),
+        migrations.AddField(
+            model_name="project",
+            name="git_checkout_command",
+            field=models.JSONField(
+                blank=True, null=True, verbose_name="Custom command to execute before Git checkout"
+            ),
+        ),
+    ]

readthedocs/projects/models.py

@@ -300,6 +300,18 @@ class Project(models.Model):
         blank=True,
         help_text=_("Short description of this project"),
     )
+
+    # Example:
+    # [
+    #     "git clone --no-checkout --no-tag --filter=blob:none --depth 1 $READTHEDOCS_GIT_CLONE_URL .",
+    #     "git checkout $READTHEDOCS_GIT_IDENTIFIER"
+    # ]
+    git_checkout_command = models.JSONField(
+        _("Custom command to execute before Git checkout"),
+        null=True,
+        blank=True,
+    )
+
     repo = models.CharField(
         _("Repository URL"),
         max_length=255,

readthedocs/projects/tests/test_build_tasks.py

@@ -1655,6 +1655,42 @@ def test_build_commands_executed_with_clone_token(
             ]
         )
 
+    @mock.patch("readthedocs.doc_builder.director.load_yaml_config")
+    def test_project_with_custom_git_checkout_command(self, load_yaml_config):
+        git_checkout_command = [
+            "env",
+            "echo $READTHEDOCS_GIT_CLONE_URL",
+            "git clone --no-checkout --no-tag --filter=blob:none --depth 1 $READTHEDOCS_GIT_CLONE_URL .",
+            "git sparse-checkout init --cone",
+            "git sparse-checkout set projects/project",
+            "git checkout $READTHEDOCS_GIT_IDENTIFIER" ,
+        ]
+        self.project.git_checkout_command = git_checkout_command
+        self.project.save()
+
+        config = BuildConfigV2(
+            {
+                "version": 2,
+                "build": {
+                    "os": "ubuntu-22.04",
+                    "tools": {
+                        "python": "3",
+                    },
+                },
+            },
+            source_file="readthedocs.yml",
+        )
+        config.validate()
+        load_yaml_config.return_value = config
+
+        self._trigger_update_docs_task()
+
+        self.mocker.mocks["git.Backend.run"].assert_has_calls(
+            [
+                mock.call(*cmd.split(), escape_command=False) for cmd in git_checkout_command
+            ]
+        )
+
     @mock.patch("readthedocs.doc_builder.director.load_yaml_config")
     def test_install_apt_packages(self, load_yaml_config):
         config = BuildConfigV2(

readthedocs/rtd_tests/tests/test_api.py

@@ -3425,6 +3425,7 @@ def test_get_version_by_id(self):
                 "documentation_type": "sphinx",
                 "environment_variables": {},
                 "features": [],
+                "git_checkout_command": None,
                 "has_valid_clone": False,
                 "has_valid_webhook": False,
                 "id": 6,

readthedocs/vcs_support/backends/git.py

@@ -44,6 +44,15 @@ def update(self):
         """Clone and/or fetch remote repository."""
         super().update()
 
+        if self.project.git_checkout_command:
+            # Run custom checkout step if defined
+            if isinstance(self.project.git_checkout_command, list):
+                for cmd in self.project.git_checkout_command:
+                    # NOTE: we need to pass ``escape_command=False`` here to be
+                    # able to expand environment variables.
+                    code, stdout, stderr = self.run(*cmd.split(), escape_command=False)
+                return
+
         # Check for existing checkout and skip clone if it exists.
         from readthedocs.projects.models import Feature
 
@@ -500,6 +509,11 @@ def checkout(self, identifier=None):
         """Checkout to identifier or latest."""
         super().checkout()
 
+        # Do not checkout anything else if the project has a custom Git checkout command.
+        # The ``git checkout`` command has to be executed inside the ``update()`` method.
+        if self.project.git_checkout_command:
+            return
+
         # NOTE: if there is no identifier, we default to default branch cloned
         if not identifier:
             return