fix: prevent git task workers from diverging during sync fan-out (#9349)

[polmichel]

Why

In a multi-worker task pool, the git sync flow fans work out across workers. When a new upstream commit landed between the orchestrator resolving HEAD and the other workers running their own git pull, workers ended up on different commits for the same repo.

Goal: make every fan-out worker converge on the exact commit the orchestrator pinned, regardless of what lands upstream during fan-out.

This PR also carries a second, independent git fix (see below).

Closes #9349

What changed

Behavioral

• The sync orchestrator now records the commit SHA it just synced and broadcasts it in RefreshGitFetch. Receiving workers check out that exact SHA instead of fast-forwarding to whatever upstream HEAD currently is.
• Separate fix: pulling a repository that had to create a missing local branch crashed when recording its commit value (an unbound infrahub_branch). The branch is now bound before the commit is written.

How to review

A commit by commit approach would be relevant since there is:

• One commit for the initial bug fix 93e86eb and one for the related test 7e2f139
• One commit for the collateral bug and related test 308110c
• One commit for the refactor 419ef91

Following commits are unitary fix or similar issue using the new pinned commit, or documentation/lint/format matter.
Extra scrutiny welcome on the pin source per flow.

How to test

# Divergence reproduction (fails before the fix, passes after)
uv run pytest backend/tests/component/message_bus/operations/git/test_refresh_git_fetch.py -x -v

# Missing-branch pull regression
uv run pytest backend/tests/component/git/test_git_repository.py -x -v

Known follow-ups (intentionally out of scope)

• That read-only flow broadcasts repository_kind=REPOSITORY for a read-only repo. Worth confirming independently.

Checklist

• Tests added/updated
• Changelog entries added (9349.fixed.md, +pull-new-branch-unbound-commit.fixed.md)
• External docs updated (no user-facing/ops-facing surface change)
• Internal .md docs updated (no knowledge-doc change needed)
• I have reviewed AI generated content

---

Summary by cubic

Prevents git task workers from diverging during sync fan-out by pinning the orchestrator’s commit and hard-resetting workers to that exact SHA under a repository lock. Also fixes a branch-creation pull crash and ensures commit values are recorded. Addresses IFC-2642.

• Bug Fixes
  • Added optional commit to RefreshGitFetch; workers now fetch and hard-reset via reset_to_commit under the repo lock, falling back to pull if the pin is missing or can’t be resolved.
  • Applied pinning across periodic sync, repository add (read/write and read-only), branch create, merge, and read-only pull; ref-only read-only flows resolve a concrete SHA once and broadcast it.
  • Fixed missing-branch pull crash by binding the branch before writing its commit; the commit value now updates when a new local branch is created.
  • Narrowed pin-resolution errors to ValueError and InvalidGitRepositoryError; added a fan-out convergence test and a commit-update test; updated RPC mocks and docs for the new commit field.

^{Written for commit 23e08ed. Summary will update on new commits. Review in cubic}

[cubic-dev-ai]

1 issue found across 8 files

Confidence score: 3/5

• There is a concrete regression risk in backend/infrahub/git/tasks.py: pull_read_only broadcasts commit=model.commit rather than the commit actually synced, which can mislead downstream workers.
• The most severe impact is user-facing sync divergence: when model.commit is None, fan-out workers may fall back to pull() and reintroduce drift instead of converging on the intended revision.
• Given the issue’s relatively high severity/confidence (7/10, 8/10), this is a meaningful but likely targeted fix rather than a broad systemic failure, so merge risk is moderate.
• Pay close attention to backend/infrahub/git/tasks.py - ensure the broadcasted commit matches the synced commit to prevent fallback pulls and divergence.

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

Re-trigger cubic</sub>

[codspeed-hq]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing pmi-IFC-2642-task-workers-diverge (23e08ed) with stable (edaeba7)¹}

Footnotes

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

[polmichel]

Is this an issue that this is tagged as REPOSITORY and not a read-only repository type?

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

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="docs/docs/reference/message-bus-events.mdx">

<violation number="1" location="docs/docs/reference/message-bus-events.mdx:82">
P2: The Type column for the `commit` field is set to "N/A", but a commit SHA is a string value. This is inconsistent with the other fields in the same table (all typed as "string").</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The Type column for the commit field is set to "N/A", but a commit SHA is a string value. This is inconsistent with the other fields in the same table (all typed as "string").

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/reference/message-bus-events.mdx, line 82:

<comment>The Type column for the `commit` field is set to "N/A", but a commit SHA is a string value. This is inconsistent with the other fields in the same table (all typed as "string").</comment>

<file context>
@@ -79,6 +79,7 @@ For more detailed explanations on how these events are used within Infrahub, see
 | **repository_kind** | The type of repository | string | None |
 | **infrahub_branch_name** | Infrahub branch on which to sync the remote repository | string | None |
 | **infrahub_branch_id** | Id of the Infrahub branch on which to sync the remote repository | string | None |
+| **commit** | Commit SHA to check out, pinned by the sync orchestrator instead of pulling the latest upstream HEAD | N/A | None |
 <!-- vale on -->
 <!-- vale off -->
</file context>

Suggested change

	| **commit** | Commit SHA to check out, pinned by the sync orchestrator instead of pulling the latest upstream HEAD | N/A | None |
	| **commit** | Commit SHA to check out, pinned by the sync orchestrator instead of pulling the latest upstream HEAD | string | None |

[polmichel]

This documentation is auto-generated. This is surely due to the fact that the field as a default value at None, but I am not totally sure.

[cubic-dev-ai]

Thanks for the context—understood that this table is auto-generated.

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Shadow auto-approve: would require human review. This PR modifies core git synchronization logic across multiple workers, introducing commit pinning and a new reset_to_commit method to prevent divergence; such changes affect a critical path for repository data integrity and require human review due to potential impact on fan-out behavior...

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Shadow auto-approve: would require human review. This PR modifies core git synchronization logic to prevent worker divergence, introducing a new reset_to_commit method, altering pull and message broadcast behavior, and changing concurrency handling under locks; while well-tested, the blast radius and risk to data integrity across all...

Re-trigger cubic</sub>