How to Use Argo CD: The Beginner's Guide (First Install, the Git-Is-the-Truth Rule, First Application, and the Sync-Policy Lesson)

CodexFuse Team · 2026-11-01T03:01:49.701Z · 15 min read

A beginner-friendly Argo CD tutorial: install on a kind cluster, follow the git-is-the-truth rule, deploy your first Application, and master sync policies, drift and ApplicationSets.

If you deploy to Kubernetes by running kubectl apply from your laptop, you know the failure mode: the cluster slowly drifts away from what you think is running, hotfixes live only in someone's terminal history, and rollbacks mean archaeology. Learning how to use Argo CD replaces that loop with a single rule — the cluster follows Git, always. Argo CD is a free, open-source, declarative GitOps continuous-delivery tool for Kubernetes: you describe the desired state of your applications in a Git repository, and Argo CD continuously makes the live cluster match it, reporting drift and syncing changes automatically. This is the argocd tutorial for beginners: the Git-is-the-truth rule, your first install on a local kind cluster, your first Application, the sync-policy lesson (manual vs automated, prune, selfHeal), drift detection, and ApplicationSets — the full beginner arc in one page. New to containers entirely? Start with our Docker beginner guide — Argo CD only makes sense once containers and clusters feel familiar.

What Is Argo CD?

Argo CD is a declarative GitOps continuous delivery tool for Kubernetes. "Declarative" means you describe what the cluster should look like — Deployments, Services, ConfigMaps — and the tool figures out how to get there. "GitOps" means that description lives in a Git repository, which becomes the single source of truth. Argo CD runs as a Kubernetes controller that continuously compares the live cluster state against the desired state in Git; anything that deviates is flagged OutOfSync, and Argo CD can sync it back automatically or wait for your click.

The project behind it is argoproj/argo-cd on GitHub — Apache-2.0 licensed, with roughly 24,505 stars, created in February 2018, and pushed as recently as today (the latest release, v3.5.6, landed October 20, 2026). Argo CD is a CNCF graduated project and sits in the Argo family alongside Argo Rollouts, Argo Workflows, and Argo Events. This gitops beginner guide treats Argo CD as the delivery half of a pipeline: something else builds your container images, Argo CD ships them.

Argo CD for Beginners: the 10-Step First-Run Arc

Here is the exact arc this argocd tutorial follows, end to end — the argocd for beginners path from zero to a synced app. Do it on a practice cluster and you will have deployed your first application from Git in about half an hour.

1. Create a practice cluster. kind create cluster — kind runs Kubernetes inside Docker containers, so you get a real cluster on your laptop for free. Argo CD needs a running cluster first; skipping this step is the number-one beginner confusion.
2. Install the Argo CD CLI. brew install argocd on macOS/Linux, or download the binary from the project's releases page. The CLI talks to the same API as the web UI.
3. Install Argo CD from a pinned manifest. kubectl create namespace argocd, then apply the install manifest for v3.5.6 (the newest stable tag as of this writing) with --server-side --force-conflicts — the flags are required because Argo CD's CRDs exceed the client-side annotation size limit. Details in the install section below.
4. Expose the API server. kubectl port-forward svc/argocd-server -n argocd 8080:443 — the server is not exposed outside the cluster by default.
5. Grab the one-shot admin password. argocd admin initial-password -n argocd, log in with argocd login localhost:8080 --insecure, and change the password immediately with argocd account update-password.
6. Point an Application at a Git repo. Use the official example apps repo (https://github.com/argoproj/argocd-example-apps.git) and the guestbook path — a ready-made demo that needs no repo of your own.
7. Watch it go OutOfSync. The new Application reports OutOfSync and Missing health — Argo CD sees the desired state in Git and nothing in the cluster yet.
8. Sync it. argocd app sync guestbook (or the Sync button in the UI) — manifests are retrieved from Git and applied, exactly like kubectl apply.
9. Break it on purpose. Edit a resource with kubectl directly and watch Argo CD flag the drift. This is the moment the Git-is-the-truth rule clicks.
10. Turn on automated sync + selfHeal. argocd app set guestbook --sync-policy automated --auto-prune --self-heal — now Git changes deploy themselves and manual edits get reverted. The sync-policy section below explains what each flag really does.

Do You Really Need a Kubernetes Cluster First?

Yes — and this is the step most argocd install guides gloss over. Argo CD is not a standalone server; it is a set of controllers that live inside a Kubernetes cluster and talk to the Kubernetes API. No cluster, no Argo CD. For practice, kind is the fastest answer: it spins up a full Kubernetes cluster as Docker containers on your laptop, free, in a couple of minutes — the standard argocd kind workflow is one command for the cluster, then Argo CD on top. If you have not picked a server for real workloads yet, our what is VPS hosting guide explains what to look for in a host that will run your cluster.

One kind-specific note for later: the Argo CD API server is a ClusterIP service by default, and on kind there is no cloud load balancer to give it an external IP. The kubectl port-forward svc/argocd-server -n argocd 8080:443 trick from step 4 is the intended access method on local clusters — do not waste an afternoon trying to make the LoadBalancer service type work on kind.

How Do You Install Argo CD?

The official quick start is two commands. First, a namespace to hold everything:

kubectl create namespace argocd

Then the install manifest. The docs ship a stable tag, but the same docs recommend pinning a version for anything you care about — so pin the newest stable release you verified today (v3.5.6, released October 20, 2026):

kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.5.6/manifests/install.yaml

The two flags are not optional decoration. --server-side is required because some Argo CD CRDs (like ApplicationSet) exceed the 262KB annotation size limit that client-side kubectl apply imposes; server-side apply avoids the limit by not storing the last-applied-configuration annotation. --force-conflicts lets the apply take ownership of fields previously managed by other tools, which is safe on a fresh install and necessary on upgrades. Verify the rollout with kubectl -n argocd get pods — you should see the API server, the repo server, the application controller, Redis, and the ApplicationSet controller all running.

How Do You Log In and Get the Admin Password?

Expose the server, then pull the one-shot initial password:

kubectl port-forward svc/argocd-server -n argocd 8080:443
argocd admin initial-password -n argocd
argocd login localhost:8080 --insecure
argocd account update-password

The initial password lives as clear text in a secret named argocd-initial-admin-secret in the argocd namespace. Change it immediately — and then delete the secret, because it serves no purpose after that and keeps the clear-text password lying around. (If you ever need a fresh one, Argo CD re-creates it on demand.) The --insecure flag is only for practice: the default install uses a self-signed certificate, and in production you configure a real one instead of waving the flag forever.

How Do You Create Your First Argo CD Application?

An argocd application is the unit of deployment: it says "take this Git repo at this path and keep this cluster namespace matching it." The fastest first Application uses the project's own example apps, so you need no repo of your own:

argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

The destination https://kubernetes.default.svc means "this same cluster" — Argo CD can deploy to itself without any cluster registration. Deploying to a different cluster is the optional step: argocd cluster add CONTEXTNAME installs an argocd-manager ServiceAccount into that cluster's kube-system namespace and binds it to an admin-level ClusterRole.

Prefer the UI? Open https://localhost:8080, click + New App, name it guestbook, keep the default project, leave the sync policy at Manual, set the repository URL to the example-apps repo with path guestbook at revision HEAD, and point the destination at the in-cluster server and the default namespace. Same Application, two doors.

Either way, the app lands in OutOfSync with Missing health — Argo CD has read Git, compared it with the cluster, and found nothing deployed yet. Sync it:

argocd app sync guestbook

That command pulls the manifests from the repo and applies them, exactly like kubectl apply. Check argocd app get guestbook: the Deployment and Service now show Synced with healthy status, and the UI draws the resource tree — the visual that makes Argo CD feel different from a CI log.

The Git-Is-the-Truth Rule

Here is the one rule that makes everything else make sense: the cluster state follows the repo, never the other way around. Do not run kubectl apply on resources Argo CD owns. It works once — then the next reconciliation reverts your edit, and the confusing back-and-forth wastes your afternoon. Every change is a commit; every deployment is a merge; Git becomes the audit log, the review process, and the rollback button.

The corollary is about secrets. The Git repo holds your desired state, which means it must never hold raw secrets — anyone with repo access gets the keys to the cluster. The security spine for a beginner is simple: keep secrets out of Git entirely and reference them from a secrets manager (our OpenBao beginner guide walks through the self-hosted option), or encrypt them in-repo with a tool like SOPS or Sealed Secrets. Pick one approach before your first real Application, not after.

What Is an Argo CD Sync Policy?

The argocd sync policy answers one question: when Git and the cluster disagree, who moves, and when? There are two modes. Manual — the default — means Argo CD detects the difference, shows OutOfSync, and waits for you to press Sync. Automated means Argo CD syncs by itself as soon as it notices drift. Switch modes with one command:

argocd app set guestbook --sync-policy automated

An argocd automated sync has two sub-switches that beginners constantly confuse, so learn them as a pair:

• Prune (--auto-prune): when a resource disappears from Git, delete it from the cluster. Off by default as a safety mechanism — automated sync will never delete anything unless you explicitly allow it.
• SelfHeal (--self-heal): when someone changes the cluster directly (a manual kubectl edit, a debugging scale-up), sync it back to the Git state automatically. Also off by default — plain automated sync only reacts to Git changes, not cluster changes.

In YAML, the full beginner-safe combo looks like this:

syncPolicy:
  automated:
    prune: true
    selfHeal: true
  syncOptions:
    - CreateNamespace=true

The sync-options line is worth knowing: CreateNamespace=true creates the destination namespace if it is missing, PrunePropagationPolicy=foreground controls how deleted resources cascade, and RespectIgnoreDifferences=true pairs with diff customization. Start manual, graduate to automated once you trust your repo, add prune and selfHeal only when you understand what each one deletes or reverts.

Two semantics details from the official docs that save real debugging time. First, an automated sync only fires when the app is OutOfSync, and only once per unique commit SHA plus parameters — if the last successful sync already ran against the same commit, a second sync is not attempted. Second, with selfHeal on, Argo CD retries the sync after the self-heal timeout (5 seconds by default, controlled by the --self-heal-timeout-seconds flag on the application controller). There is also an allowEmpty guard that stops automated sync with pruning from ever emptying an application by accident — automation with a seatbelt.

What Is Drift, and How Does Argo CD Detect It?

Drift is any difference between the desired state in Git and the live state in the cluster — a replica count someone bumped by hand, a label a dashboard added, a resource deleted out-of-band. Argo CD's application controller continuously reconciles every Application: it fetches the desired manifests from the repo server, reads the live objects from the Kubernetes API, and diffs them. Anything that deviates is OutOfSync, visualized per-resource in the UI tree.

Try it on the guestbook: kubectl scale deployment guestbook-ui --replicas=5, then refresh the app. Without selfHeal, Argo CD flags it and waits — the drift is visible, the cluster is wrong, and the decision is yours. With selfHeal, the controller reverts the replica count within seconds. That experiment is the whole philosophy in miniature: visibility first, automation only when you ask for it.

What Is an ApplicationSet?

One Application deploys one thing to one place. Real teams deploy dozens of things to dozens of places — and writing one Application YAML per service per environment does not scale. An ApplicationSet is a template that generates Applications from generators:

• List generator — a hardcoded list of elements (service names, environments), each rendered into an Application.
• Git generator — reads directories or files from a Git repo; add a folder, get an Application.
• Cluster generator — reads registered clusters and their labels; label a cluster env=prod, and matching Applications appear there. This is the officially recommended way to bootstrap many clusters.

Generators support Go templates plus Sprig functions, so names, namespaces, and sync policies can be computed per element. The related pattern is app-of-apps: one root Application points at a directory of other Application manifests, so adding a service is just committing its Application YAML and letting Argo CD self-register it. Start with single Applications, reach for an ApplicationSet when you catch yourself copy-pasting the same YAML for the fifth environment.

Argo CD vs FluxCD: Which One Should a Beginner Pick?

FluxCD is the other major GitOps operator for Kubernetes, and the argocd vs fluxcd question comes down to shape, not philosophy: both implement the same GitOps pattern — Git as the source of truth, reconciliation loop, drift correction. The practical beginner difference is shape, not philosophy. Argo CD is one control plane with a rich web UI: you see every application, its sync status, and its resource tree in a browser, which is why this guide recommends it as the first GitOps tool to learn. Flux takes a toolkit approach — a set of focused controllers (source, kustomize, helm) driven primarily from the CLI — which many teams prefer once they are automating at scale and no longer want a UI in the loop.

Both are CNCF projects, both are free and open source, and learning one teaches you 80% of the other: the GitOps contract — every change is a commit, the cluster is a function of Git — is identical. Pick Argo CD if you want to see GitOps working; evaluate Flux later when your delivery is fully automated and you want the leaner, CLI-native shape. There is no wrong answer, and no lock-in: the Git repo holding your desired state moves between them.

The 3-Minute Lesson: Why Your Commit Does Not Deploy Instantly

The most common beginner panic: you push a commit, stare at Argo CD, and nothing happens. Nothing is broken. By default, Argo CD polls Git repositories — it does not get pushed to. The polling interval is the timeout.reconciliation value in the argocd-cm ConfigMap, which defaults to 180 seconds (3 minutes, plus a small jitter). So a commit can take up to about three minutes to even be noticed, and only Applications with automated sync enabled will then deploy it.

The fix for speed is webhooks: Argo CD integrates with GitHub, GitLab, and Bitbucket, so a push event triggers a refresh immediately instead of waiting for the next poll. The production pattern the docs suggest is webhooks for responsiveness plus a longer polling interval for resilience — if a webhook fails (network hiccup, misconfiguration), the poll still catches the change. Setting timeout.reconciliation to 0 disables polling entirely, which the docs explicitly do not recommend, because then a missed webhook means a missed deployment.

Where Do Helm and CI Fit? The Three-Lane Picture

Argo CD deploys; it does not build. The full pipeline has three lanes, and Argo CD is the last one. Lane one is packaging: Helm charts describe how an application is assembled from templates and values — our Helm beginner guide covers it, and Argo CD renders Helm charts natively as an Application source type. Lane two is CI: a pipeline builds the container image and updates the image tag in the Git repo — our GitHub Actions beginner guide covers that lane. Lane three is delivery: Argo CD notices the new tag in Git and syncs it to the cluster. Draw the line once and the tooling stops overlapping: CI pushes image tags to Git, Argo CD pulls desired state from Git, Helm describes what gets rendered. Never rivals — one pipeline.

7 Beginner Mistakes (and What to Do Instead)

Sources

Every fact in this guide was verified against a live source on 2026-11-01: GitHub API — argoproj/argo-cd repository (24,505 stars, Apache-2.0, created 2018-02-09, pushed 2026-11-01) and releases (v3.5.6, published 2026-10-20); Argo CD official documentation — getting started guide (install commands, --server-side --force-conflicts rationale, pin-version recommendation, argocd admin initial-password, guestbook Application, manual sync policy default), automated sync policy page (prune/selfHeal defaults and CLI flags, one-sync-per-SHA semantics, 5/10/20/40/80s retry delays, 5s self-heal timeout, timeout.reconciliation 180s default), FAQ (3-minute default polling interval, timeout.reconciliation: 0 warning), and feature list (webhook integrations, SSO, sync hooks); AWS EKS Argo CD concepts page (automated sync example manifest with CreateNamespace=true); k8s.guide Argo CD ecosystem page (CNCF graduated status, Argo family, application-controller architecture).

Frequently Asked Questions

Is Argo CD free?

Yes. Argo CD is Apache-2.0 licensed open source that you self-host inside your own Kubernetes cluster — no subscription, no per-seat pricing, no open-core split. Commercial distributions exist (Akuity, Codefresh, Red Hat OpenShift GitOps), but they package the same upstream project. Your only cost is the cluster it runs on.

Do I need Kubernetes before installing Argo CD?

Yes — Argo CD is a set of controllers that run inside a Kubernetes cluster, not a standalone server. For practice, kind (Kubernetes in Docker) gives you a real local cluster in minutes with kind create cluster. Argo CD then deploys to that same cluster via https://kubernetes.default.svc with no extra registration.

Should I use manual or automated sync?

Start manual. Manual sync (the default) shows you OutOfSync and waits for your click, which teaches you to read drift before you automate it away. Move to automated sync when every change reliably flows through Git pull requests; add prune and selfHeal only when you can explain what each one deletes or reverts without looking it up.

Why is my app OutOfSync right after I created it?

That is the expected first state, not an error. Argo CD has read your Git repo, compared it with the cluster, and found the resources missing — the app is OutOfSync with Missing health until the first sync. Run argocd app sync <name> (or press Sync in the UI) and it moves to Synced.

Argo CD vs FluxCD — which should I learn first?

Learn Argo CD first if you want to see GitOps working: its web UI shows every application, its sync status, and its resource tree, which makes the reconciliation loop concrete. Flux is the CLI-native, controller-toolkit alternative many teams prefer at scale. Both implement the same contract — the cluster is a function of Git — so the second one takes a weekend once you know the first.