In a traditional CI/CD setup, a pipeline pushes changes to your cluster and then forgets about them. If someone edits a deployment by hand afterwards, nothing notices. GitOps flips this around: a controller inside the cluster continuously compares the live state with the desired state stored in Git, and corrects any difference. This guide introduces GitOps with Argo CD, the most popular GitOps controller for Kubernetes, and deploys a real application with it.
What GitOps Actually Means – GitOps with Argo CD
GitOps rests on four ideas:
- The entire system is described declaratively, usually as Kubernetes YAML in a Git repository.
- The Git repository is the single source of truth. If it is not in Git, it should not exist in the cluster.
- Software agents pull the desired state from Git and apply it automatically. Nothing pushes into the cluster from outside.
- The same agents watch for drift and continuously work to match the live state to Git (self-healing).
The practical benefits are significant: every change is a Git commit with an author and a review trail, rollbacks are a git revert, and a destroyed cluster can be rebuilt by pointing Argo CD at the same repository.
Prerequisites – GitOps with Argo CD
- A running Kubernetes cluster. A local Minikube installation on Ubuntu is perfect for learning.
kubectlconfigured to talk to the cluster.- A Git repository (public, for the first experiment) containing Kubernetes manifests.
Step 1: Install Argo CD
Argo CD runs inside its own namespace:
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl get pods -n argocd
Wait until all pods show Running. Then expose the web UI locally with a port-forward:
kubectl port-forward svc/argocd-server -n argocd 8080:443
The initial admin password is stored in a secret. The username is admin:
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d; echo
Open https://localhost:8080, log in, and change the password under User Info. Exploring the UI is the fastest way to build intuition for GitOps with Argo CD before you automate anything.

Step 2: Declare an Application
In GitOps, even Argo CD’s own applications are declared as YAML. An Application resource tells Argo CD which Git repository and path to watch, and where to deploy:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: demo-app
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/YOUR-USERNAME/YOUR-REPO.git
targetRevision: HEAD
path: k8s
destination:
server: https://kubernetes.default.svc
namespace: default
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
Apply it with kubectl apply -f application.yaml. Two automated options matter here: prune: true deletes resources that disappear from Git, and selfHeal: true reverts manual edits made directly in the cluster. Together they make Git the real source of truth rather than a suggestion.
Step 3: Make a Change the GitOps Way
Now edit a manifest in Git, for example change the replica count or the container image tag, commit, and push. Within about three minutes (the default polling interval), Argo CD detects the new commit, marks the application OutOfSync, and because automated sync is enabled, applies the change itself. Edit the same deployment with kubectl scale and watch Argo CD undo your change. That small experiment teaches the GitOps model better than any diagram.
Step 4: Roll Back
Because every state lives in Git history, a rollback is simply:
git log --oneline
git revert <bad-commit-sha>
git push
Argo CD then syncs the cluster back to the previous known-good state. There is no special rollback tooling to learn and no mystery about what changed: the diff is a normal Git diff.
Troubleshooting Common Problems
Application stuck in OutOfSync
Open the application in the UI and read the sync status and events. Common causes are invalid YAML, a missing namespace, or a resource the Argo CD service account cannot create. The UI’s app diff view shows exactly which fields differ.
Repository cannot be reached
For private repositories, add credentials under Settings > Repositories using a personal access token or an SSH deploy key, and confirm the cluster has outbound network access.
Sync keeps reverting a field you want
Some controllers, especially HorizontalPodAutoscaler, legitimately fight GitOps over fields like replica counts. Use the ignoreDifferences section of the Application to exclude those fields from comparison.
Best Practices for Production GitOps
When Argo CD manages more than a demo, structure matters. Use the app-of-apps pattern: one root Application that creates child Applications, so an entire environment is bootstrapped from a single kubectl apply. Separate configuration repositories from application code repositories; the CI pipeline builds images and updates image tags in the config repo, while developers review config changes like code. For multiple environments, keep a base set of manifests with per-environment overlays (Kustomize is the common choice) instead of copying folders that drift apart. Enable SSO and RBAC early, because the Argo CD UI can change production. Add notifications for failed syncs, and use sync waves and hooks when ordering matters, for example running database migrations before the new app version. Finally, back up your Git repositories religiously: in GitOps, Git history is your disaster-recovery plan.
Conclusion
GitOps with Argo CD turns deployments into a continuous, auditable reconciliation between Git and your cluster: declare the desired state, let the controller apply it, and roll back with a Git revert. Start with one small application and automated sync, then grow toward app-of-apps structures and multiple environments. The Argo CD official documentation covers advanced topics such as SSO, projects, and sync waves when you are ready.