ArgoCD Operations

ArgoCD manages GitOps deployments for the cluster. This document covers operational procedures for ArgoCD.

GitHub Webhook Configuration

ArgoCD receives push notifications from GitHub via webhook to trigger immediate syncs (instead of waiting for polling).

Webhook Architecture

GitHub (org webhook) → Cloudflare Tunnel → ArgoCD Server
     push event         argocd-wh.fzymgc.net    /api/webhook

Initial Setup

Prerequisites:

• Cloudflare Tunnel deployed and healthy
• ArgoCD running with webhook secret configured

Step 1: Get webhook secret from Vault

vault kv get -field=webhook.github.secret secret/fzymgc-house/cluster/argocd

Step 2: Configure GitHub organization webhook

1. Go to: https://github.com/organizations/fzymgc-house/settings/hooks
2. Click “Add webhook”
3. Configure:

Field	Value
Payload URL	https://argocd-wh.fzymgc.net/api/webhook
Content type	application/json
Secret	(paste from Step 1)
Events	”Just the push event”
Active	✅

4. Click “Add webhook”

Step 3: Verify webhook delivery

1. Push to any fzymgc-house repository
2. Check webhook deliveries at: https://github.com/organizations/fzymgc-house/settings/hooks
3. Look for green checkmark and 200 response

Verification

Test	Command	Expected
DNS resolves	dig argocd-wh.fzymgc.net	CNAME to cfargotunnel.com
Endpoint reachable	curl -I https://argocd-wh.fzymgc.net/api/webhook	400 (missing payload) or 200
Webhook delivery	Push to repo, check GitHub	Green ✓, 200 response
ArgoCD refresh	Check app sync after push	Immediate (not 3-min delay)

Troubleshooting

Symptom	Cause	Fix
401/403 response	Webhook secret mismatch	Verify secret in Vault matches GitHub config
404 response	Tunnel route missing	Check Cloudflare Tunnel ingress config
502 response	ArgoCD unreachable	Check argocd-server pod status
No sync after push	Repo URL mismatch	Verify Application repo URL matches webhook source

Check ArgoCD logs for webhook activity:

kubectl logs -n argocd -l app.kubernetes.io/name=argocd-server --tail=100 | rg -i webhook

Disabling Webhook

To revert to polling-only mode:

1. Delete the GitHub organization webhook
2. ArgoCD automatically falls back to polling (default: 3 minutes)

No ArgoCD configuration changes required.

Sync Pitfall: RespectIgnoreDifferences + array jqPathExpressions

Do not combine syncOptions: RespectIgnoreDifferences=true with ignoreDifferences.jqPathExpressions that address array elements (e.g. .spec.data[].remoteRef.conversionStrategy on ExternalSecrets). ArgoCD’s sync-time normalizer cannot merge arrays when items are added or removed — an upstream-acknowledged limitation (the TestNormalizeTargetResources case for new array entries is skipped as “limitation in the current implementation”). The failure mode: the sync reports Succeeded at the right revision, map-typed fields apply, but the live array silently keeps its old value. On ExternalSecrets this leaves ESO in SecretSyncedError (a synced template can end up referencing keys the stale spec.data doesn’t fetch) and the app sits OutOfSync indefinitely.

ignoreDifferences alone (without RespectIgnoreDifferences) still normalizes the diff, so schema-defaulted fields (ESO’s conversionStrategy/decodingStrategy/metadataPolicy) don’t cause perpetual OutOfSync — the sync simply applies the true desired manifest and the API server re-defaults those fields. The apps still carrying the option have additional ignore rules (StatefulSet volumeClaimTemplates server fields, CRD /status, Argo Workflow template inputs/outputs, webhook configs) pending individual analysis before removal.

To unstick a sync already in this state, apply the git-desired manifest with ArgoCD’s own field manager:

git show origin/main:<path-to-manifest> | \
  kubectl apply --server-side --field-manager=argocd-controller --force-conflicts -f -

Access

URL	Purpose
https://argocd.fzymgc.house	Web UI
https://argocd-wh.fzymgc.net/api/webhook	GitHub webhook endpoint

Related Documentation

• Cloudflare Operations - Tunnel configuration
• HCP Terraform - GitOps automation
• Vault Operations - Secret management