aldengolab/ArgoCD Helm Deployment Validation

ArgoCD Helm Deployment Validation

Follow this procedure to validate a Helm-based ArgoCD GitOps deployment end-to-end: run pre-flight auth checks, monitor sync status, evaluate health per resource type, debug issues, apply approved fixes, and retry until the deployment is confirmed healthy.

Pre-Flight Checks

Before doing anything else, verify CLI state and cluster context.

ArgoCD Login

Check login state:

argocd account get-user-info

If authenticated, continue. If unauthenticated, follow this credential flow in order:

Tier 1 — SSO (preferred):

argocd login <server> --sso

This opens a browser for SSO authentication and stores a token in ~/.argocd/config. No credentials pass through this session.

Tier 2 — Stored token: If SSO is unavailable, check whether a valid token already exists:

argocd account get-user-info

If a stored token works, continue. Do not prompt for credentials.

Tier 3 — User runs login in terminal: If no valid session exists and SSO is unavailable, do NOT ask for a password. Instead, instruct the user:

"Please run argocd login <server> in your terminal to authenticate, then return here. I'll wait."

After the user confirms they've logged in, re-run argocd account get-user-info to verify before continuing.

Never embed a password in a command. Credentials passed through the chat session may be stored in session history.

Self-signed certificates: If your ArgoCD server uses a self-signed certificate, add the CA to your system trust store rather than using --insecure. Using --insecure disables all TLS verification and exposes the session to MITM attacks on any network path.

Kubernetes Context

Check current context:

kubectl config current-context
kubectl config get-contexts

If the context looks incorrect for this deployment (wrong cluster name, wrong environment), suggest the likely correct context and ask for confirmation before switching:

kubectx <context-name>

Git Branch Check

Check the current branch:

git branch --show-current

• If not on main, proceed with commits on the current branch.
• If on main, ask the user: "You're on main — should I commit fixes directly to main, or create a new branch?"

App Discovery and Targeting

Explicit App Name

If an app name is provided, target it directly:

argocd app get <app-name>

Auto-Discovery

If no app name is provided, list all apps in the ArgoCD namespace and present them:

argocd app list -o json

Filter to apps on the current cluster context. If multiple apps exist, ask the user which to monitor, or monitor all if the user says so.

Sync Status Evaluation

After identifying the target app(s), check sync and health status using the argocd_read(group="app", command="get", app_name="<app-name>") MCP tool, or via Bash if the tool is unavailable:

argocd app get <app-name> --output json

Evaluate the response:

| Sync Status | Health Status | Action | |-------------|---------------|--------| | Synced | Healthy | [OK] Validate k8s Events and logs (see below) | | Synced | Progressing | [WAIT] Apply timing logic before escalating | | Synced | Degraded | [DEBUG] Invoke argocd-debugger agent immediately | | OutOfSync | — | [SYNC] Run argocd app sync <app-name> then re-check. If argocd_read(group="app", command="diff", app_name="<app-name>") indicates no diff (e.g. (no diff — desired and live state match)), invoke argocd-outofsync-empty-diff-operator-crd skill instead | | Unknown | — | [INVESTIGATE] Check resources, look for sync errors |

If sync was recently triggered and status is Progressing, apply the Timing Logic below before escalating to debug.

Sync Timing Logic

Do not immediately flag a progressing sync as failed. Use this logic:

1. At 5 minutes: Run per-resource health checks (see references/health-checks.md). If resources are actively progressing (new log lines, pod restarts decreasing), note status and wait.
2. At 10 minutes: If no clear forward progress, treat as stalled — invoke argocd-debugger agent.
3. Static resources (ConfigMap, Secret, Service, Ingress, Role, RoleBinding, ClusterRole, CRD, PVC): Any sync error on these is a configuration problem — debug immediately, do not wait.

Kubernetes Health Validation (Synced + Healthy)

When ArgoCD reports Synced + Healthy, validate that the application is actually running correctly by checking k8s Events and logs in the app's namespace.

Check Events

Use the k8s_namespace_health(<namespace>) MCP tool to get pod statuses and warning events in a single call, or via Bash:

kubectl get events -n <namespace> --sort-by='.lastTimestamp' | tail -40
kubectl get pods -n <namespace>

Look for: Warning events, BackOff, Failed, OOMKilled, Evicted, FailedMount, Unhealthy.

Check Pod Logs

For pod logs, use get_pod_logs(<namespace>, <pod>, errors_only=True) or:

kubectl logs -n <namespace> <pod-name> --tail=100
# For previous crash:
kubectl logs -n <namespace> <pod-name> --previous --tail=100

If Events or logs contain errors, invoke argocd-debugger agent to investigate and propose fixes.

Confirming Healthy

A deployment is confirmed healthy when:

• ArgoCD status: Synced + Healthy
• No Warning events in the namespace
• Pod logs show no errors and application is serving/running normally
• All expected resources exist and are in Running/Completed state

Invoking the Debugger

When issues are detected, invoke the argocd-debugger agent with context:

• App name and namespace
• Current sync/health status
• Any error messages seen so far
• The specific resource(s) that are failing

The debugger will investigate, propose file changes, get approval, apply fixes, commit, push, and trigger a re-sync.

After a Fix Is Applied

After the debugger commits and pushes:

1. Wait for ArgoCD to detect the new commit (typically 30-90 seconds, or trigger manually: argocd app sync <app-name>)
2. Re-run the full sync status evaluation from the top
3. Continue the loop until confirmed healthy

Known Stuck Sync Patterns

For known stuck-sync diagnoses and fixes (PreSync hook TTL race, ArgoCD controller OOMKilled during large-chart SSA sync), read: Read skills/argocd-helm-validation/references/stuck-sync-patterns.md

• references/sync-debugging.md — Detailed ArgoCD sync error investigation procedures, common error patterns, and resolution steps
• references/health-checks.md — Per-resource-type health check procedures (Deployments, StatefulSets, Jobs, Pods, static resources)
• references/fix-and-retry.md — How to propose, edit, commit, push, and re-sync fixes; git workflow; values.yaml and Chart fix patterns

Related Skills

If the debugger identifies that kubectl changes are reverting immediately, a git push isn't updating a deployed resource, or two tools appear to be contesting the same resource, invoke the argocd-helm-eso-setups skill. It covers the ownership model, selfHeal behavior, prune scope, fixed-name collision points, and how to transfer a resource between Helm and ArgoCD management.