🐙 GitOps With Argo CD: A Practical Starting Guide

I resisted GitOps for a while. kubectl apply from CI worked, more or less. Then we had the incident where someone hot-fixed a Deployment directly in the cluster, the next CI run silently reverted it, and the outage came back at 4pm. That’s the day GitOps stopped being optional for me.

GitOps means Git is the source of truth, and a controller in the cluster continuously reconciles reality to match it. No more kubectl apply from laptops, no more drift you can’t explain. Argo CD is the tool I reach for. Here’s how to start without making the classic mistakes.

The core idea: pull, not push

Traditional CI pushes to the cluster — your pipeline holds cluster credentials and runs kubectl apply. GitOps pulls: Argo CD runs inside the cluster, watches a Git repo, and applies changes itself. Two big wins:

1. No cluster credentials in CI. Your pipeline only pushes to Git. The blast radius of a leaked CI token shrinks dramatically.
2. Continuous reconciliation. If anything drifts from Git — a manual edit, a deleted resource — Argo CD notices and can correct it.

Structure your repo before you install anything

The repo layout determines whether GitOps stays sane at scale. The pattern that holds up:

clusters/
  prod/
    apps/         # Argo CD Application manifests
  staging/
apps/
  api/
    base/         # kustomize base or Helm chart
    overlays/
      prod/
      staging/

Keep config separate from the app source code. The app repo builds an image and writes the new tag into the config repo; Argo CD watches the config repo. Mixing them means every code commit triggers a deploy reconcile, which you don’t want.

The Application object

Argo CD’s unit of work is an Application — it points at a repo path and a destination:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: api-prod
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/config
    targetRevision: main
    path: apps/api/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: payments
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Two settings deserve thought:

• prune: true lets Argo CD delete resources you removed from Git. Without it, deleted manifests linger in the cluster forever. With it, a bad Git revert can delete live resources — so review changes carefully.
• selfHeal: true reverts manual cluster edits back to Git state. This is the feature that would have prevented my 4pm outage — but it also means break-glass manual fixes get stomped, so know it’s on.

Start with manual sync, graduate to automated

For the first few weeks, leave automated off and sync by hand from the UI or CLI:

argocd app sync api-prod
argocd app diff api-prod

app diff is the killer feature — it shows you exactly what Argo CD would change before it does. Watch a few syncs, build trust, then turn on automated, then selfHeal. Flipping all the switches on day one is how people get burned.

App-of-apps for managing many Applications

Once you have dozens of Applications, manage them with an app-of-apps: one root Application whose source is a directory of other Application manifests. Now adding a new service is a Git commit, not a kubectl apply, and your Argo CD config is itself under GitOps. It’s recursion, and it’s the right kind.

Where AI helps in a GitOps flow

GitOps shifts the risk from “what did someone run” to “what’s in this PR” — and a PR diff is exactly what AI reviews well. Before merging a change to the config repo, ask:

“This is a diff to a Kustomize overlay that Argo CD auto-syncs to production with prune enabled. Flag anything that would delete a live resource, change an immutable field, or drop a replica count to zero.”

That prune clause is the one that bites — a refactor that moves a resource between files can read as a delete-plus-create. Keep a set of GitOps review prompts handy, and run config-repo PRs through the Code Review tool before they merge, since in GitOps the merge is the deploy.

Drift, health, and sync status

Argo CD gives you three signals worth watching:

• Sync status — does the cluster match Git? OutOfSync means drift.
• Health status — are the resources actually healthy? A synced-but-unhealthy app means the manifests applied but the pods aren’t ready.
• Sync waves — annotate resources with argocd.argoproj.io/sync-wave to order them (CRDs before the controllers that use them, namespaces before the workloads in them).

Sync waves solve the “it works on the second apply” problem where a resource depends on something created in the same batch.

A safe adoption path

How I’d onboard a team:

1. Separate config from code into a dedicated repo.
2. Install Argo CD, point one non-critical app at it, sync manually.
3. Watch app diff until you trust what it does.
4. Enable automated + prune, then selfHeal, one app at a time.
5. Adopt app-of-apps once you have more than a handful.
6. Treat config-repo PRs as deploys — review them like production changes.

GitOps doesn’t eliminate mistakes; it makes them visible, reviewable, and revertible with a git revert. The cluster stops being a place where state mysteriously accumulates and becomes a faithful rendering of a repo you can read, diff, and roll back. That alone is worth the migration.

AI review of GitOps changes is assistive. Always inspect argocd app diff before syncing to production.