ci(tests[benchmarks]): Add CodSpeed performance benchmarks

why: Track GitSync.obtain (and future hot paths) for performance regressions in
CI. Replaces the long-stalled poetry-era #471 with a uv-native, functional-tests
implementation against current master.

what:
- pyproject.toml: add `pytest-codspeed` to `testing` group; register a
  `benchmark` marker; deselect benchmarks by default via `addopts`; let mypy
  ignore missing `pytest_codspeed.*` stubs
- tests/benchmarks/test_sync_git.py: add functional-style benchmark for
  `GitSync.obtain` against an initial-commit remote
- .github/workflows/tests.yml: add `benchmarks` job using
  `CodSpeedHQ/action@v3` on pull requests and master pushes
- CHANGES: note the benchmark addition under 0.41.x

Author: tony

.github/workflows/tests.yml

@@ -54,6 +54,25 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 
+  benchmarks:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' || github.ref == 'refs/heads/master'
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.14
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+      - name: Run benchmarks via CodSpeed
+        uses: CodSpeedHQ/action@v3
+        with:
+          token: ${{ secrets.CODSPEED_TOKEN }}
+          run: uv run --group testing py.test tests/benchmarks --codspeed -m benchmark
+
   release:
     runs-on: ubuntu-latest
     needs: build

CHANGES

@@ -20,6 +20,15 @@ $ uv add libvcs --prerelease allow
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Development
+
+#### CI: CodSpeed performance benchmarks
+
+- Add `pytest-codspeed` to the `testing` dependency group
+- Register a `benchmark` marker (deselected by default; opt-in via `pytest tests/benchmarks --codspeed -m benchmark`)
+- Add `tests/benchmarks/test_sync_git.py` covering `GitSync.obtain` of an initial-commit remote
+- Add a dedicated `benchmarks` job in `.github/workflows/tests.yml` that runs the CodSpeed action on PRs and master pushes
+
 ## libvcs 0.40.0 (2026-04-25)
 
 ### What's new

pyproject.toml

@@ -97,6 +97,7 @@ testing = [
   "pytest-rerunfailures",
   "pytest-mock",
   "pytest-watcher",
+  "pytest-codspeed",
 ]
 coverage =[
   "codecov",
@@ -146,6 +147,10 @@ files = [
   "tests",
 ]
 
+[[tool.mypy.overrides]]
+module = ["pytest_codspeed.*"]
+ignore_missing_imports = true
+
 [tool.coverage.run]
 branch = true
 parallel = true
@@ -231,7 +236,8 @@ addopts = [
   "--showlocals",
   "--doctest-docutils-modules",
   "-p no:doctest",
-  "--reruns=2"
+  "--reruns=2",
+  "-m", "not benchmark",
 ]
 doctest_optionflags = [
   "ELLIPSIS",
@@ -243,6 +249,9 @@ testpaths = [
   "docs",
   "README.md",
 ]
+markers = [
+  "benchmark: codspeed performance benchmark, deselected by default (run via `pytest tests/benchmarks --codspeed`)",
+]
 filterwarnings = [
   "ignore:The frontend.Option(Parser)? class.*:DeprecationWarning::",
 ]

tests/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Benchmark tests run via pytest-codspeed."""

tests/benchmarks/test_sync_git.py

@@ -0,0 +1,30 @@
+"""Benchmark suite for git sync operations via pytest-codspeed."""
+
+from __future__ import annotations
+
+import typing as t
+
+import pytest
+
+from libvcs.pytest_plugin import CreateRepoFn
+from libvcs.sync.git import GitSync
+
+if t.TYPE_CHECKING:
+    import pathlib
+
+    from pytest_codspeed.plugin import BenchmarkFixture
+
+
+@pytest.mark.benchmark
+def test_git_obtain_initial_commit_repo(
+    create_git_remote_repo: CreateRepoFn,
+    tmp_path: pathlib.Path,
+    benchmark: BenchmarkFixture,
+) -> None:
+    """Benchmark `GitSync.obtain` against a remote with one initial commit."""
+    remote = create_git_remote_repo()
+    repo = GitSync(url=f"file://{remote}", path=tmp_path / "checkout")
+
+    benchmark(repo.obtain)
+
+    assert repo.get_revision() == "initial"