The Engineer's Guide to Argo CD: GitOps Done Right

If you've ever had a deployment fail because someone applied a hotfix manually and forgot to commit it, you know exactly why GitOps exists.

Kubernetes is complex. Managing it with a pile of shell scripts and kubectl apply commands is a recipe for drift, confusion, and outages.

Argo CD solves this by making Git the absolute source of truth. You don't verify if your cluster is up-to-date; Argo CD does. You don't rollback by re-running a Jenkins job; you git revert.

(Still comparing tools? Read our Argo CD vs Flux CD breakdown).

This guide isn't a documentation rehash. It's a walkthrough of how to set up Argo CD the way we actually use it in production.

Why We Bet on Argo CD

There are plenty of CD tools out there, but Argo CD won the war for a few reasons (see State of the Cloud Trends):

1. It's a "Pull" model: It runs inside your cluster. You don't need to give your CI server (Jenkins/GitHub Actions) admin access to your K8s cluster.
2. The UI is actually useful: It visually maps your Deployments, Services, and Pods. When something breaks, you see exactly what and where.
3. Drift Detection: It shouts at you (or auto-heals) when the cluster state doesn't match Git.

1. Getting It Running

Let's get an instance up. We'll stick to the standard installation for this guide, but in production, you'd likely use the Helm chart.

Install

First, create a namespace and apply the manifest. This installs the API server, the repo server (which talks to Git), and the application controller.

Note: The stable manifest tracks the latest release. For production, pin to a specific version or use the Helm chart for easier upgrades.

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

Wait until everything is running:

kubectl get pods -n argocd -w

Accessing the UI

For local testing, just port-forward:

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

Now open https://localhost:8080.

Pro Tip: The certificate is self-signed, so your browser will complain. Just proceed.

To log in, the default user is admin. Argo generates a random password initially. Grab it with:

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

Security Note: This secret is meant to be deleted. Once you log in, change the password or, better yet, configure OIDC (SSO) immediately.

2. Defining Your First Application

In Argo, an Application connects a Source (Git repo) to a Destination (Cluster + Namespace).

You can create apps via the UI, but seasoned engineers define them declaratively using YAML. This is "GitOps for your GitOps tool."

Here is a manifest for a simple demo app:

1apiVersion: argoproj.io/v1alpha1
2kind: Application
3metadata:
4  name: guestbook
5  namespace: argocd
6spec:
7  project: default
8  source:
9    repoURL: https://github.com/argoproj/argocd-example-apps.git
10    targetRevision: HEAD
11    path: guestbook
12  destination:
13    server: https://kubernetes.default.svc
14    namespace: guestbook
15  syncPolicy:
16    automated: 
17      prune: true       # Delete resources if they disappear from Git
18      selfHeal: true    # Revert manual changes in the cluster
19    syncOptions:
20      - CreateNamespace=true

Save this as application.yaml and apply it:

kubectl apply -f application.yaml

If you look at the UI, you'll see the "guestbook" app spin up, sync, and turn green.

3. The Magic of specific Sync Policies

The syncPolicy block above is critical. Let's break down what we usually turn on:

• automated: Without this, Argo CD just "watches." It won't act until you click Sync. We generally enable this for Dev/Staging environments.
• prune: true: This is essential. If you delete a file in Git, Argo will delete the resource in K8s. Without this, you get orphaned resources.
• selfHeal: true: The enforcer. If someone manually deletes a Deployment or scales it down, Argo detects the drift and fixes it immediately.

Production advice: Some teams disable automated sync for Production to have a "human in the loop" approval before the final rollout, or they use Argo Rollouts for canary releases.

4. Structuring Your Git Repos

The most common question we get: How should I organize my repos?

The "App of Apps" Pattern

Managing 50 Application YAML files manually is painful. The solution is the App of Apps pattern.

You create one "Parent Application" that points to a folder in Git. That folder contains the YAML files for all your other Applications.

Argo deploys the Parent, which sees the children, creating all your apps in one shot.

Repo Layout

We recommend splitting your source code from your config.

Repo 1: The App Code (/my-app)

• Source code, optimized Dockerfile
• CI pipeline builds image -> pushes to registry -> updates Repo 2

Repo 2: The GitOps Config (/k8s-manifests)

• Helm charts, Kustomize overlays
• Application manifests
• This is what Argo CD watches

This separation stops infinite loops in CI and keeps your precise cluster state clean.

5. Handling Secrets

Do not commit raw Kubernetes Secrets to Git. Just don't.

Argo CD doesn't handle secret encryption natively. You need a partner tool. We typically see two approaches:

1. Sealed Secrets: You encrypt the secret on your laptop into a SealedSecret CRD (safe for Git). The controller in the cluster decrypts it. Best for smaller teams.
2. External Secrets Operator (ESO): You store secrets in AWS Secrets Manager / HashiCorp Vault. ESO fetches them and creates K8s Secrets. Best for enterprise.

6. What About Multi-Cluster?

Argo CD is a centralized control plane. You don't need to install it on every cluster.

You install it once (say, on a tools cluster). Then you register your other clusters:

argocd cluster add <kube-context-name>

Now, in your Application manifest, you just change the destination:

destination:
  server: https://prod-cluster-api-url.com
  namespace: backend

Summary

Argo CD is the engine of modern Kubernetes operations. It forces discipline—if it's not in Git, it doesn't exist.

The Checklist for Success:

• Install Argo CD via Helm.
• Separate source code from config repos.
• Pick a secret management strategy (ESO or Sealed Secrets).
• Use "App of Apps" or ApplicationSets to manage fleet-wide apps.

Once you trust it, look into Argo Rollouts to do Blue/Green and Canary deployments properly. But that's a guide for another day.

Need help architecting your GitOps pipeline? Contact us at Coding Protocols. We've seen every failure mode so you don't have to.

For the same setup driven from Azure DevOps rather than GitHub, see GitOps with Argo CD and Azure DevOps.

Frequently Asked Questions

Should application manifests live with the application code?

Usually a separate repository. Keeping them together means every code commit triggers a deployment evaluation and the two histories tangle. A separate manifest repository gives deployment its own review and history, and makes a release a small reviewable change rather than a side effect.

What is the difference between automated sync and self-heal?

Automated sync applies changes when Git moves ahead. Self-heal additionally reverts changes made directly in the cluster, so a manual edit is undone at the next reconcile. Enable self-heal when Git must be the only source of truth, and accept that emergency manual fixes will be reverted unless committed.

How should secrets be handled?

Not in the manifest repository in plaintext. Either encrypt them in Git with SOPS or Sealed Secrets, or keep them in a secret manager and sync with External Secrets Operator. The encrypted-in-Git approach keeps everything in one place; the operator approach keeps the secret out of Git entirely and is usually the cleaner boundary.

Argo CD or Flux?

Argo CD if you want a UI that makes sync state legible to people outside the platform team. Flux if you would rather have no UI to run and express everything as custom resources. Both are CNCF graduated and handle the same core job — the shape of the tool matters more than the feature list.

Official References

• Argo CD declarative setup — the Application and AppProject spec
• Argo CD sync options — prune, self-heal and sync-wave behaviour