fix(git): narrow the repository lock to git working-copy mutations

[polmichel]

Intent

This branch narrows the repository lock so it only guards the git working-copy mutations (clone, fetch, worktree creation) and no longer wraps the object import into the graph.

The object import reads file content from a per-commit worktree that is pinned while the lock is held, so it does not need the lock itself. By moving the import outside the critical section, repositories can import concurrently while the on-disk git state stays correctly serialized.

A reusable, mock-free lock-recording test adapter underpins the series, so the "import runs outside the lock" guarantee is asserted directly from the recorded acquire/release boundaries.

Intermediate PRs

Each PR below was reviewed and approved before being merged into this branch:

PR	Title	Approved
#9439	test: reusable lock recording adapter	Yes, merged 2026-06-04
#9440	fix(git): run object import outside the repository lock during sync	Yes, merged 2026-06-08
#9441	fix(git): run object import outside the repository lock when adding a repository	Yes, merged 2026-06-08

🤖 Generated with Claude Code

---

Summary by cubic

Narrowed the repository lock to only clone/fetch/worktree operations, and moved object imports outside the lock for sync and add-repository to reduce contention and allow concurrent imports. init() now fetches a missing commit under the lock when needed.

• Bug Fixes

  • Run imports after releasing the repository lock in both sync and add-repo flows; git state mutations remain serialized.
  • InfrahubRepository.init() fetches a missing commit under the repository lock, then retries; still raises if absent.
  • create_commit_worktree() is local-only and raises CommitNotFoundError on a local miss (no implicit fetch).

• Refactors

  • Introduced RepositorySyncer, RepositoryAdder, RepositoryImporter, and RepositoryFileImporter.
  • Split sync flow: collect_pending_imports() returns PendingObjectImport; sync() executes imports afterward.
  • Updated tasks to use the new components; existing RefreshGitFetch notifications are preserved.
  • Added a lock-recording test adapter and timeline to assert that imports run outside the repository lock.

^{Written for commit 60a1bbd. Summary will update on new commits.}

[cubic-dev-ai]

5 issues found across 16 files

Confidence score: 3/5

• There is a concrete regression risk in backend/infrahub/git/tasks.py: running import outside the lock without pinning a commit can import from a moved branch head, causing inconsistent objects.
• backend/infrahub/git/repository.py has a medium-high reliability risk because postponing imports until after full collection may skip imports already gathered if a later branch operation fails.
• Lock-scope changes in backend/infrahub/git/sync.py still appear to hold the repository lock across graph/API work (collect_pending_imports and InfrahubRepository.new()), so contention and throughput issues are still likely; the backend/tests/component/git/test_git_rpc.py note is minor/readability-only.
• Pay close attention to backend/infrahub/git/tasks.py, backend/infrahub/git/repository.py, and backend/infrahub/git/sync.py - race conditions and lock scope here can affect correctness and sync performance.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/tests/component/git/test_git_rpc.py">

<violation number="1" location="backend/tests/component/git/test_git_rpc.py:392">
P3: Unused fixture parameter `git_repos_dir`: the variable is declared in the function signature but never referenced in the function body, which is misleading for readers.</violation>
</file>

<file name="backend/infrahub/git/tasks.py">

<violation number="1" location="backend/infrahub/git/tasks.py:296">
P1: Import runs outside the lock without a pinned commit, creating a race where branch head can change before object import.</violation>
</file>

<file name="backend/infrahub/git/repository.py">

<violation number="1" location="backend/infrahub/git/repository.py:82">
P1: Deferring all imports until after full collection can drop imports for already-processed branches when a later branch operation raises.</violation>
</file>

<file name="backend/infrahub/git/sync.py">

<violation number="1" location="backend/infrahub/git/sync.py:51">
P2: `RepositoryAdder` keeps the repo lock during `InfrahubRepository.new()`, which includes async graph commit updates.</violation>

<violation number="2" location="backend/infrahub/git/sync.py:88">
P2: Repository lock still wraps graph/API calls via `collect_pending_imports`, so contention remains higher than intended.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Import runs outside the lock without a pinned commit, creating a race where branch head can change before object import.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At backend/infrahub/git/tasks.py, line 296:

<comment>Import runs outside the lock without a pinned commit, creating a race where branch head can change before object import.</comment>

<file context>
@@ -288,55 +283,56 @@ async def sync_remote_repositories() -> None:
-                    infrahub_branch_name=infrahub_branch,
-                    infrahub_branch_id=branches[infrahub_branch].id,
-                    commit=pinned_commit,
+                await repo.import_objects_from_files(  # type: ignore[call-overload]
+                    git_branch_name=default_import_git_branch, infrahub_branch_name=infrahub_branch
                 )
</file context>

[cubic-dev-ai]

P1: Deferring all imports until after full collection can drop imports for already-processed branches when a later branch operation raises.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At backend/infrahub/git/repository.py, line 82:

<comment>Deferring all imports until after full collection can drop imports for already-processed branches when a later branch operation raises.</comment>

<file context>
@@ -65,6 +75,23 @@ async def sync(self, staging_branch: str | None = None) -> None:
+            GraphQLError: When creating a branch in the graph fails for a reason other than the branch already existing.
+
+        """
+        for pending in await self.collect_pending_imports(staging_branch=staging_branch):
+            await self.import_objects_from_files(
+                infrahub_branch_name=pending.infrahub_branch_name,
</file context>

[cubic-dev-ai]

P2: RepositoryAdder keeps the repo lock during InfrahubRepository.new(), which includes async graph commit updates.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At backend/infrahub/git/sync.py, line 51:

<comment>`RepositoryAdder` keeps the repo lock during `InfrahubRepository.new()`, which includes async graph commit updates.</comment>

<file context>
@@ -0,0 +1,90 @@
+
+    async def add(self, model: GitRepositoryAdd) -> InfrahubRepository:
+        async with self._lock_registry.get(name=model.repository_name, namespace="repository"):
+            repo = await InfrahubRepository.new(
+                id=model.repository_id,
+                name=model.repository_name,
</file context>

[cubic-dev-ai]

P2: Repository lock still wraps graph/API calls via collect_pending_imports, so contention remains higher than intended.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At backend/infrahub/git/sync.py, line 88:

<comment>Repository lock still wraps graph/API calls via `collect_pending_imports`, so contention remains higher than intended.</comment>

<file context>
@@ -0,0 +1,90 @@
+
+    async def sync(self, repo: InfrahubRepository, staging_branch: str | None = None) -> None:
+        async with self._lock_registry.get(name=repo.name, namespace="repository"):
+            pending_imports = await repo.collect_pending_imports(staging_branch=staging_branch)
+        for pending_import in pending_imports:
+            await self._importer.import_branch(repo, pending_import)
</file context>

[cubic-dev-ai]

P3: Unused fixture parameter git_repos_dir: the variable is declared in the function signature but never referenced in the function body, which is misleading for readers.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At backend/tests/component/git/test_git_rpc.py, line 392:

<comment>Unused fixture parameter `git_repos_dir`: the variable is declared in the function signature but never referenced in the function body, which is misleading for readers.</comment>

<file context>
@@ -380,3 +384,31 @@ async def test_new_repository(self, setup: None, prefect_test_fixture: None) ->
+async def test_add_git_repository_releases_lock_before_import(
+    prefect_test_fixture: None,
+    git_upstream_repo_01: dict[str, str],
+    git_repos_dir: Path,
+) -> None:
+    """The default-branch import must run after the repository lock held for the clone is released."""
</file context>

[codspeed-hq]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing pmi-20260507-longduration (60a1bbd) with stable (2146d13)¹}

Footnotes

1. No successful run was found on stable (83a7695) during the generation of this report, so 2146d13 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩