GitOps With ArgoCD: From Hype to Stable Production

Actualizado: 2026-05-03

ArgoCD^[1] has gone in a few years from an interesting project to the standard deploy practice for Kubernetes. GitOps — where the Git repository is the single source of truth for the cluster’s desired state — has proven to work better than traditional push pipelines for many teams. This guide covers the principles, what ArgoCD does well, the mistakes seen in production, and the comparison with Flux.

Key takeaways

• GitOps isn’t just “deploy from Git”: its essence is continuous reconciliation that corrects drift automatically.
• ArgoCD stands out for its rich UI, mature multi-tenancy, and broad Helm, Kustomize, and plain YAML support.
• The app-of-apps pattern lets you manage the entire cluster declaratively.
• Secrets never go in the config repository — use Sealed Secrets or External Secrets Operator.
• The right sync mode for production at the start is manual; scale toward auto-sync as confidence grows.

The Four Real GitOps Principles

GitOps has four formal principles:

1. Declarative: the entire system is described declaratively (Kubernetes YAML, Helm/Kustomize manifests), not as a sequence of commands.
2. Versioned and immutable: the desired state lives in Git. Every change is an auditable commit.
3. Automatically pulled: agents in the cluster pull from the repository and apply changes. No external push from CI.
4. Continuous reconciliation: the agent constantly compares actual vs desired state and corrects drift.

The most important implication is the fourth. If someone edits a resource by hand (kubectl edit), ArgoCD reverts it to the Git state. That difference from traditional pipelines is the core value.

Why ArgoCD Has Won Adoption

ArgoCD is the most popular option because it combines several strengths:

• Excellent UI: visual view of applications, their resources, health state, and diff between Git and cluster.
• Serious multi-tenancy: supports multiple teams with granular permissions via RBAC + projects.
• Flexible sync policies: manual, auto, with prune, with self-heal — every combination useful for different scenarios.
• Broad tool support: Helm, Kustomize, plain YAML, and Jsonnet coexist in the same cluster.
• App-of-apps pattern: an ArgoCD app that deploys other ArgoCD apps — useful for managing the entire cluster declaratively.
• Sync waves and hooks: control over deployment order when it matters (CRDs before resources using them).

Typical Repository Structure

config-repo/
├── applications/
│   ├── prod/
│   │   ├── app-a.yaml      # ArgoCD Application pointing to manifests
│   │   └── app-b.yaml
│   └── staging/
│       └── ...
├── manifests/
│   ├── app-a/
│   │   ├── base/           # Kustomize base
│   │   └── overlays/
│   │       ├── prod/
│   │       └── staging/
│   └── app-b/
│       └── helm/           # Helm chart or values
└── argocd-bootstrap/       # ArgoCD's own configuration

Patterns that work:

• Separate app code from configuration: configuration changes don’t require image rebuild.
• Directories per environment (Kustomize overlays) over branches — easier to see differences.
• Image automation with automated commits: ArgoCD Image Updater detects new images and commits to the config repo.

Sync Policies: When to Use Each

• Manual sync: someone presses “Sync” after Git changes. Recommended in production initially.
• Auto-sync without prune: applies changes but doesn’t delete resources disappearing from Git. Conservative.
• Auto-sync with prune: applies all changes and deletes what’s no longer in Git. Dangerous if someone accidentally deletes something.
• Self-heal: in addition to applying Git, reverts any manual change. Real strict GitOps.

Progressive recommendation: manual in production at first, auto-sync without prune in staging, self-heal in dev. Move production to controlled auto-sync as team confidence grows.

Common Production Mistakes

The mistakes seen most in real projects:

• Self-heal without team discipline: if someone changes something by hand for debugging and ArgoCD reverts it within a minute, frustration follows. Clear policy: manual changes only in documented emergencies.
• Secrets in Git: never. Use Sealed Secrets, External Secrets Operator, or similar.
• Monstrous config repositories: a single repo with 200 apps is slow to sync. Split by domain or team.
• Misused sync waves: too many inter-wave dependencies complicates deploys. Keep the graph simple.
• CRDs as normal apps: CRDs must precede resources using them. Use sync waves or a separate bootstrap app.
• No ArgoCD config backups: ArgoCD itself must be in Git (app-of-apps). If the cluster dies, you recover with argocd app create pointing to the config repo.
• Cluster admin for everyone: configure ArgoCD projects with limited permissions per team and namespace.

Comparison With Flux

Flux^[2] is the other mature GitOps tool. The most relevant practical differences:

• UI: ArgoCD has a rich native UI; Flux’s is more limited (improving with Weave GitOps).
• Multi-tenancy: ArgoCD uses projects; Flux uses Kubernetes native namespaces.
• Philosophy: ArgoCD feels more like an “application”; Flux feels more like “controllers in the cluster”.
• Image automation: Flux has it natively; ArgoCD requires the Image Updater component.
• Multi-cluster: ArgoCD supports managing multiple clusters from one instance; Flux assumes one instance per cluster.

Read the full Flux vs ArgoCD comparison for more detail. Both are graduated CNCF projects and solid choices; the difference is which fits your team better.

Conclusion

ArgoCD has consolidated GitOps as a mature deploy practice for Kubernetes. Well implemented — with team discipline, secrets managed separately, and sync policies appropriate to the environment — it improves deploy reliability, audit trail, and recovery speed. Poorly implemented — with secrets in Git, monstrous configuration, and no backups — it just adds another layer of complexity. The difference lies in operational details, not the tool.

1. ArgoCD
2. Flux