Diagnosing Argo CD ApplicationSet Git Credential Failures: A Step‑by‑Step Guide

Recognizable Condition

When the ApplicationSet controller cannot clone a Git repository, the pod logs will show messages such as git-client: failed to clone repository or authentication failed. In the Argo CD UI the ApplicationSet status will remain Pending or show Failed with a reason that references a Git error.

Root Causes

Failures typically arise from one of the following:

• Missing or mis‑referenced Git credential secret.
• Incorrect secret keys or wrong type.
• Network or DNS issues preventing the controller from reaching the Git provider.
• Passphrase‑protected SSH keys (Argo CD does not support them).
• Cross‑namespace secret access that is not permitted.

Diagnostic Table

Cause	Symptom in Logs	Diagnostic Check	Fix
Secret missing or wrong namespace	"failed to clone repository"	kubectl get secret -n $NS $SECRET_NAME	Create the secret in the correct namespace or update the ApplicationSet spec to reference the existing one.
Wrong key names (HTTPS)	"authentication failed"	kubectl describe secret $SECRET_NAME -n $NS	Ensure keys username and password exist.
Wrong key names (SSH)	"authentication failed"	kubectl describe secret $SECRET_NAME -n $NS	Ensure key sshPrivateKey exists and is not passphrase protected.
Secret not Opaque	"unsupported secret type"	kubectl get secret $SECRET_NAME -n $NS -o yaml | grep type	Set type: Opaque in the secret definition.
Network/DNS blocked	"repository not found" or timeout	kubectl exec -it -n $NS $POD -- git ls-remote $REPO_URL	Verify egress rules and DNS resolution for the Git provider.

Ordered Checks & Fixes

1. Verify the secret exists and is in the right namespace.

   Run:
   kubectl get secret -n $NS $SECRET_NAME

   • If missing, create it: kubectl create secret generic $SECRET_NAME -n $NS --from-literal=username=... --from-literal=password=...
2. Confirm the secret type is Opaque.

   Run:
   kubectl get secret -n $NS $SECRET_NAME -o jsonpath={.type}

   • Change type if needed: kubectl patch secret $SECRET_NAME -n $NS -p '{\"type\":\"Opaque\"}'
3. Check key names and values.

   Run:
   kubectl describe secret -n $NS $SECRET_NAME

   • For HTTPS: keys username and password.
   • For SSH: key sshPrivateKey and no passphrase.
4. Validate network reachability.

   From a pod in the same namespace, attempt a manual clone:
   kubectl exec -it -n $NS $POD -- git clone $REPO_URL

   • Observe any DNS or timeout errors. If they occur, review egress rules or VPN settings.
5. Restart the ApplicationSet controller pod to apply changes.

   Run:
   kubectl delete pod -n $NS -l app.kubernetes.io/name=argocd-applicationset-controller

   • The pod will recreate automatically. Check logs for success.

Example ApplicationSet Spec

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: demo-appset
spec:
  generators:
    - git:
        repoURL: https://github.com/example/repo.git
        revision: main
        directories:
          - path: .
  template:
    metadata:
      name: '{{path.basename}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/repo.git
        targetRevision: main
        path: '{{path}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: default
  git:
    # Reference the secret containing credentials
    secretRef: my-git-credentials

Escalation Criteria

If all the above checks pass but the controller still cannot clone the repository:

• Verify that the Git URL is correct and the branch/revision exists.
• Check for rate limiting or authentication throttling from the Git provider.
• Inspect the ApplicationSet controller logs for stack traces that may indicate bugs or missing dependencies.
• If the issue persists, file an issue on the Argo CD GitHub repository or open a support ticket with your cloud provider.

Limitations & Practical Checks

• The guide assumes a standard Argo CD installation with the ApplicationSet controller running in the argocd namespace. Adjust namespace names accordingly.
• The secret must be Opaque; other types (e.g., kubernetes.io/tls) are not supported for Git credentials.
• SSH keys must not be passphrase protected; if you need a passphrase, use an SSH agent or Argo CD's SSH key support.
• Cross‑namespace secret access requires the appropriate RoleBinding or ClusterRoleBinding granting get on secrets in the target namespace.

To verify the fix, watch the ApplicationSet status in the Argo CD UI or run:
kubectl get applicationset demo-appset -o jsonpath={.status.conditions[?(@.type==\"Sync\")]}