GitOps with ArgoCD: A Practical Beginner's Guide for Kubernetes

"What's running in production right now?" If the honest answer is "whatever someone last applied with kubectl," you have a configuration drift problem waiting to happen. GitOps fixes it with one rule: the desired state of your cluster lives in Git, and an agent makes the cluster match it. ArgoCD is the most popular agent for the job.

Here's how the model works and how to set it up for real.

The idea in one paragraph

You stop running kubectl apply by hand. Instead, your manifests (or Helm charts, or Kustomize overlays) live in a Git repository. ArgoCD watches both the repo and the cluster, shows you when they differ, and syncs them — automatically or at the click of a button. Every production change becomes a pull request, with history, review, and an instant rollback via git revert.

Install ArgoCD on your cluster

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Wait for the pods to come up, then get the admin password and expose the UI:

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d

kubectl port-forward svc/argocd-server -n argocd 8080:443

Open https://localhost:8080, log in as admin with that password, and change it immediately. For a permanent setup, front it with an ingress and TLS — our Kubernetes ingress guide covers that part.

Point it at a repository

The fastest way to learn is a small app repo of your own: a folder with deployment.yaml and service.yaml for something trivial (an Nginx deployment works fine).

Create an Application in the UI — or as YAML, which is more in the spirit of GitOps:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: demo
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/yourname/gitops-demo.git
    targetRevision: main
    path: manifests
  destination:
    server: https://kubernetes.default.svc
    namespace: demo
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

automated means ArgoCD syncs on every commit, prune removes resources deleted from Git, and selfHeal reverts manual changes made directly in the cluster — that's the drift-killer.

Apply it with kubectl apply -f application.yaml and watch the UI: within a minute, your app appears, syncs, and goes green.

The moment it clicks

Edit the replica count in Git, commit, push. ArgoCD notices and scales the deployment. Then — the important test — run kubectl scale by hand to a different number and watch selfHeal snap it back to Git's value. That's the whole value proposition in one demo: production can never silently differ from the repo.

Practical advice from the field

• One repo per team or per app, with folders per environment (env/staging, env/production) rather than branches per environment. Branches diverge; folders just diff.
• Don't auto-sync everything on day one. Start with manual sync on production so a bad commit requires a human click; automate staging first.
• Secrets don't go in Git. Use Sealed Secrets, External Secrets Operator, or your cloud's secret store. Our ConfigMaps and Secrets guide covers the options.
• Rollbacks are git revert + sync, not archaeology. Keep commits small and you'll love this on your worst day.

A safe first week with ArgoCD

Start with one non-critical application and leave automatic pruning off until you understand its behavior. Pruning is useful, but deleting a manifest in Git also gives ArgoCD permission to delete the corresponding cluster resource. That is exactly what you want eventually, and a painful surprise when a path or sync option is wrong.

Watch the application's Health and Sync states separately. “Synced” means the manifests match Git; it does not prove every pod is healthy. A deployment can match the repository perfectly and still crash because its image, configuration, or database is wrong.

Keep the initial admin credentials out of scripts, configure proper user access, and back up any Git repository settings that are not themselves declared elsewhere. Once the basic workflow is reliable, add staging automation, then production approvals, and only then broader pruning and self-healing.

Is it worth it for small setups?

For a single toy cluster, ArgoCD can feel like overhead. But the moment you have more than one environment or more than one person deploying, GitOps stops being ceremony and starts being the only sane way to answer "who changed what, when, and how do we undo it."