FluxCD GitRepository Reconcile Debugger

Threat/Impact Level: HIGH | Downtime Risk: HIGH | Time to Fix: 5–20 mins

TL;DR

• What broke: FluxCD's source-controller cannot reach the Git remote — the GitRepository object is stuck in False/NotReady, which cascades and blocks every Kustomization and HelmRelease that depends on it.
• How to fix it: Validate the URL scheme, confirm the secretRef credential secret exists and is correctly typed, check egress NetworkPolicies and corporate proxy settings, and verify TLS/CA trust.
• Fast path: Use our Client-Side Sandbox above to paste your GitRepository manifest — it auto-diagnoses and refactors the YAML without sending your tokens anywhere.

NAMESPACE    NAME          READY   MESSAGE                                                              REVISION   SUSPENDED
flux-system  app-repo      False   failed to checkout and determine revision: unable to clone           
                                   'https://github.com/org/private-repo': Get "https://github.com":    
                                   dial tcp: i/o timeout

Status:
  Conditions:
    Message:   failed to checkout and determine revision: 
               unable to clone 'git@github.com:org/repo.git': 
               ssh: handshake failed: knownhosts: key mismatch
    Reason:    GitOperationFailed
    Status:    False
    Type:      Ready

How to Fix It

Step 1: Triage the Exact Failure Reason

# Get the precise status message
kubectl get gitrepository app-repo -n flux-system -o jsonpath='{.status.conditions[*].message}'

# Check source-controller logs for the raw error
kubectl logs -n flux-system deploy/source-controller --since=10m | grep -E 'error|failed|unable'

# Force an immediate reconcile attempt
flux reconcile source git app-repo -n flux-system --timeout=60s

Fix A: Wrong URL or Protocol Mismatch

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: app-repo
  namespace: flux-system
spec:
- url: git@github.com:org/repo  # missing .git suffix, causes clone failure
+ url: ssh://git@github.com/org/repo.git
  interval: 1m0s
  secretRef:
    name: github-ssh-key

Note: For HTTPS, use https://github.com/org/repo. For SSH, Flux requires the ssh:// scheme explicitly — the SCP-style [email protected]:org/repo.git is not universally accepted across controller versions.

Fix B: Missing or Malformed SSH Secret

The secretRef must contain identity, identity.pub, and known_hosts keys. A missing known_hosts causes the knownhosts: key mismatch error.

# Wrong secret structure (missing known_hosts)
apiVersion: v1
kind: Secret
metadata:
  name: github-ssh-key
  namespace: flux-system
type: Opaque
data:
- identity: <base64-private-key>
- identity.pub: <base64-public-key>
# known_hosts is absent — source-controller rejects the host

+ identity: <base64-private-key>
+ identity.pub: <base64-public-key>
+ known_hosts: <base64-of-github-known-hosts-entry>

Generate the correct secret:

# Scan and capture GitHub's current host key
ssh-keyscan github.com > /tmp/known_hosts 2>/dev/null

# Create the Flux SSH secret correctly
flux create secret git github-ssh-key \
  --url=ssh://git@github.com/org/repo.git \
  --private-key-file=./deploy_key \
  --known-hosts-file=/tmp/known_hosts \
  --namespace=flux-system

Fix C: Egress Blocked by NetworkPolicy

If your cluster has default-deny egress, source-controller cannot reach the Git remote.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-source-controller-egress
  namespace: flux-system
spec:
  podSelector:
    matchLabels:
      app: source-controller
  policyTypes:
  - Egress
  egress:
- [] # no egress rules — all outbound blocked
+ - ports:
+   - port: 443
+     protocol: TCP
+   - port: 22
+     protocol: TCP

Fix D: Corporate Proxy / Self-Signed CA

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: app-repo
  namespace: flux-system
spec:
  url: https://git.internal.corp/org/repo.git
  interval: 1m0s
- # No CA reference — TLS verification fails against internal CA
+ certSecretRef:
+   name: internal-ca-cert  # Secret must contain 'ca.crt' key
  secretRef:
    name: gitlab-https-token

Enterprise Best Practice: Automate Secret Rotation with External Secrets Operator

Hardcoded deploy tokens expire. Wire ExternalSecret to Vault or AWS Secrets Manager so the SSH key secret auto-rotates:

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: github-ssh-key
  namespace: flux-system
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: github-ssh-key
+   template:
+     type: Opaque
  data:
+   - secretKey: identity
+     remoteRef:
+       key: secret/flux/github-deploy-key
+       property: private_key
+   - secretKey: known_hosts
+     remoteRef:
+       key: secret/flux/github-deploy-key
+       property: known_hosts

💡 Tired of pasting proprietary infrastructure configs into public LLMs? Generic AI interfaces log your company's ARNs, connection strings, and private keys. StackEngine enforces client-side zero-trust boundaries—the sandbox above executes 100% locally in your browser. Drop your broken manifest above to redact secrets locally and synthesize deterministic patch drafts with your own API key.

(For CI/CD pipeline automation, install via npm i -g stackengine).

# In your GitHub Actions / GitLab CI pipeline
kubeconform -strict -schema-location default \
  -schema-location 'https://raw.githubusercontent.com/fluxcd/flux2/main/config/crd/bases/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
  ./clusters/production/flux-system/

package fluxcd.gitrepository

deny[msg] {
  input.kind == "GitRepository"
  not input.spec.secretRef
  msg := sprintf("GitRepository '%v' has no secretRef — will fail on private repos", [input.metadata.name])
}

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: gitrepository-not-ready
  namespace: flux-system
spec:
  summary: "GitRepository failed to reconcile"
  providerRef:
    name: slack-ops
  eventSeverity: error
  eventSources:
    - kind: GitRepository
      name: "*"
  inclusionList:
    - ".*failed.*"
    - ".*NotReady.*"

checkov -d ./clusters/ --framework kubernetes \
  --check CKV_K8S_35  # Secrets not hardcoded as env vars

# Run from a pod in the flux-system namespace to validate reachability
kubectl run ssh-test --rm -it --image=alpine -n flux-system -- \
  sh -c "apk add openssh-client && ssh -T git@github.com -o StrictHostKeyChecking=yes"