Flux GitRepository "reference not found" (branch/tag/semver) in CI

By Kaveh Alemi·Latchkey

source-controller cloned the repo but could not resolve the ref in spec.ref. The named branch or tag does not exist, or the semver range matched no published tag, so there is nothing to check out.

What this error means

A GitRepository shows "False" with "reference not found" or "no tags matching the semver range". The repo authenticates fine; only the ref resolution fails.

unable to clone 'https://github.com/acme/infra': reference not found

Common causes

The branch or tag was renamed or deleted

The spec.ref.branch or spec.ref.tag points at a ref that no longer exists on the remote after a rename or cleanup.

The semver range matches no tag

A spec.ref.semver constraint like >=1.0.0 finds no matching tag, often because tags are unprefixed while the range expects v or vice versa.

How to fix it

Point spec.ref at a ref that exists

1. List the remote refs to see the real branches and tags.
2. Update spec.ref to a branch, tag, or semver range that matches.
3. Reconcile the source and confirm the revision resolves.

spec:
  ref:
    branch: main
  # or: tag: v1.4.0
  # or: semver: ">=1.4.0"

Check what the source resolved to

Confirm the resolved revision after fixing the ref so you know CI deploys the intended commit.

flux get sources git infra
flux reconcile source git infra

How to prevent it

• Keep GitRepository refs in sync with the branches and tags you actually publish.
• Match the semver prefix (v or none) to your tagging convention.
• Prefer immutable tags for release sources so refs do not disappear.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation