ci(downstream): test releases with CLI and Gix backends

The downstream runner always installed plain `GitPython` into a fresh
virtual environment. Starting it from a Gix-enabled environment therefore
still exercised the CLI backend and left downstream Gix compatibility
untested.

Add `--backend {cli,gix}`, retaining CLI as the default. Gix runs install
this editable checkout with `.[gix]` and verify the selected backend before
running downstream tests. Include the backend in `result.json`, status
output and retained directory names. Expand the five-project CI matrix to
ten independent jobs and document local backend selection.

Validated all five selected suites with official `GixPython` 0.1.0 first,
then CLI, using the existing Python 3.12.14 interpreter and Git 2.54.0:
72 passed and one credential-dependent DataHub skip per backend. Tested
LangChain Community 0.4.2, MLflow 3.17.0, Bandit 1.9.4, SWE-bench 5.0.2,
and DataHub 1.7.0.14 with matching release sources on both backends.

Verified the default CLI installation and backend mismatch rejection in
both directions, frozen dependencies, result metadata, and workflow matrix
wiring. `ruff check`, `ruff format --check`, runner `--help`, and
`git diff --check` passed. The ten local runs took 69.75 seconds for Gix
and 80.80 seconds for CLI including source and environment setup; these
are downstream validation timings, not controlled performance benchmarks.

Author: codex

.github/workflows/downstream.yml

@@ -17,6 +17,7 @@ jobs:
       fail-fast: false
       matrix:
         project: [langchain, mlflow, bandit, swebench, datahub]
+        backend: [gix, cli]
     steps:
       - uses: actions/checkout@v7
         with:
@@ -34,4 +35,4 @@ jobs:
           version: '0.12.13'
           enable-cache: false
       - name: Test latest release against this checkout
-        run: uv run test/downstream/run.py "${{ matrix.project }}"
+        run: uv run test/downstream/run.py "${{ matrix.project }}" --backend "${{ matrix.backend }}"

test/downstream/README.md

@@ -5,16 +5,24 @@ Run released projects' GitPython-related tests against this checkout with
 
 ```sh
 uv run test/downstream/run.py bandit
+uv run test/downstream/run.py bandit --backend gix
 uv run test/downstream/run.py bandit --version 1.9.4
-for project in langchain mlflow bandit swebench datahub; do
-    uv run test/downstream/run.py "$project"
+for backend in gix cli; do
+    for project in langchain mlflow bandit swebench datahub; do
+        uv run test/downstream/run.py "$project" --backend "$backend"
+    done
 done
 ```
 
 The default resolves the latest release from PyPI each time. `--version` reproduces
-a release; `--python` selects the test interpreter (default: 3.12). The runner
-creates a fresh environment, replaces GitPython with this editable checkout, and checks
-the imported module before testing. Upstream test files are not modified.
+a release; `--python` selects the test interpreter (default: 3.12), including an
+existing interpreter's path. `--backend` selects `cli` (the default) or `gix`.
+The runner creates a fresh environment and installs this editable checkout,
+adding the official GixPython release through `.[gix]` for Gix runs. It verifies
+both the imported checkout and the selected backend before testing, and records
+the backend in `result.json` and the default work-directory name. Starting the
+runner from a Gix environment alone does not select Gix in the isolated test
+environment. Upstream test files are not modified.
 
 Source, the environment, frozen requirements, JUnit results, and release provenance
 are retained under `.cache/downstream/`. `--work-dir PATH` uses a new directory
@@ -35,7 +43,7 @@ and test-only dependencies are excluded. Downloads are not unique installations.
 | Project | Distribution downloads | Last tested release | Selected coverage |
 | --- | ---: | --- | --- |
 | LangChain Community | 27,882,881 | 0.4.2 | 2 upstream GitLoader tests: real clones, commits, checkout, tree traversal, ignored paths, and remote validation |
-| MLflow (`mlflow-skinny`) | 25,850,354 | 3.16.1 | 47 upstream tests: 31 repository/project/model-versioning cases plus 16 Git context and credential-redaction contract cases |
+| MLflow (`mlflow-skinny`) | 25,850,354 | 3.17.0 | 47 upstream tests: 31 repository/project/model-versioning cases plus 16 Git context and credential-redaction contract cases |
 | Bandit | 24,935,372 | 1.9.4 | 12 upstream baseline CLI tests: real repository creation, commits, branches, resets, discovery, and dirty state |
 | SWE-bench | 22,942,741 | 5.0.2 | 4 supplemental integration cases for `AutoContextManager`; no upstream tests cover its GitPython callers |
 | DataHub (`acryl-datahub`) | 5,019,402 | 1.7.0.14 | 7 upstream tests passed, 1 credential-dependent skip: public clone/checkout, SSH timeout, exception/redaction contracts, and configuration |
@@ -94,6 +102,8 @@ The private SSH-clone test retains its upstream skip: the runner removes its
 credential variable and needs no private credentials. `ssh`, public GitLab
 access, and local TCP sockets are needed for the selected tests.
 
-CI runs the same command against the latest release and fails when no test passes,
-including when all selected tests are skipped. Test dependency ranges only supply
-the upstream test harness; they do not pin the dependent's release.
+CI runs all five projects against the latest release with both CLI and Gix
+backends, for ten independent jobs. A backend mismatch or a run in which no
+test passes fails the job, including when all selected tests are skipped.
+Test dependency ranges only supply the upstream test harness; they do not pin
+the dependent's release.

test/downstream/run.py

@@ -88,6 +88,7 @@ def main():
     profiles = json.loads((HERE / "projects.json").read_text())
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("project", choices=profiles)
+    parser.add_argument("--backend", choices=("cli", "gix"), default="cli", help="Backend to install and verify")
     parser.add_argument("--version", help="Release to reproduce; defaults to PyPI's latest release")
     parser.add_argument("--python", default="3.12", help="Python used by the isolated test environment")
     parser.add_argument("--work-dir", type=Path, help="New directory for retained source, environment, and results")
@@ -100,8 +101,8 @@ def main():
     else:
         cache = CHECKOUT / ".cache" / "downstream"
         cache.mkdir(parents=True, exist_ok=True)
-        work = Path(tempfile.mkdtemp(prefix=f"{args.project}-{version}-", dir=cache))
-    print(f"Testing {args.project} {version}; retained work directory: {work}", flush=True)
+        work = Path(tempfile.mkdtemp(prefix=f"{args.project}-{version}-{args.backend}-", dir=cache))
+    print(f"Testing {args.project} {version} with {args.backend}; retained work directory: {work}", flush=True)
 
     config = work / "gitconfig"
     config.write_text(
@@ -134,25 +135,35 @@ def expand(value):
     if profile.get("no_deps"):
         run(install + ["--no-deps"] + list(map(expand, profile["no_deps"])), env=env)
     # Replace the released dependency even if the downstream pins another version.
-    run(install + ["--reinstall-package", "gitpython", "-e", str(CHECKOUT)], env=env)
+    requirement = str(CHECKOUT) + ("[gix]" if args.backend == "gix" else "")
+    run(install + ["--reinstall-package", "gitpython", "-e", requirement], env=env)
 
     # Check the import used by tests and by downstream Python subprocesses.
     run(
         [
             str(python),
             "-c",
-            "import os, pathlib, git; "
+            "import os, pathlib, sys, git; from git import _backend; "
             "expected = pathlib.Path(os.environ['GITPYTHON_CHECKOUT']) / 'git' / '__init__.py'; "
             "assert pathlib.Path(git.__file__).resolve() == expected.resolve(), git.__file__; "
+            "print('GitPython backend:', _backend.name); "
+            "assert _backend.name == sys.argv[1], f'Expected {sys.argv[1]} backend, got {_backend.name}'; "
             "print('GitPython:', git.__file__); print(git.Git().version()); "
             "assert git.Git().version_info >= (2, 52), 'Git 2.52 or newer is required'",
+            args.backend,
         ],
         cwd=source,
         env=env,
     )
     with (work / "requirements-frozen.txt").open("w") as output:
         run(["uv", "pip", "freeze", "--python", str(python)], env=env, stdout=output)
-    result = {"project": args.project, "version": version, "source": provenance, "gitpython": str(CHECKOUT)}
+    result = {
+        "project": args.project,
+        "version": version,
+        "backend": args.backend,
+        "source": provenance,
+        "gitpython": str(CHECKOUT),
+    }
     result_path = work / "result.json"
     result_path.write_text(json.dumps(result, indent=2) + "\n")
     report = work / "junit.xml"