CI/CD
Advanced 17 min read CI/CD

GitOps & ArgoCD

GitOps makes the git repository the single source of truth for infrastructure and application state. ArgoCD continuously reconciles the cluster toward that desired state. Learn desired versus actual state, sync and self-healing, Application resources, and promotion between environments.

GitOpsdesired stateactual statesyncreconcileArgoCDApplicationself-healingpromotionpull-based
Prerequisites: Designing Pipelines Deployment Strategies
Introduction

What is this?

GitOps is a pattern where a git repository is the single source of truth for what runs in a cluster. Operators like ArgoCD watch the repository and reconcile the cluster: they compare the desired state (git) with the actual state (cluster), and when they differ they converge by applying the desired manifests. Deployments become pull-based — the cluster pulls from git, rather than CI pushing into the cluster.

Motivation

Why do you need it?

  • Git provides versioning, review and audit for infrastructure changes — the same guarantees as application code.
  • Declarative desired state means the cluster always converges to a known, documented configuration.
  • Self-healing operators roll back manual drift automatically, so the cluster cannot quietly diverge.
  • Rollbacks are trivial: point the repository at an older commit and the operator applies it.
  • CI no longer needs cluster credentials — it only writes to git, which dramatically shrinks the attack surface.
Think about it

Mental model

Imagine

A thermostat keeping a room at a set temperature

Think of

ArgoCD reconciling a cluster

You set a target temperature (desired state). The thermostat measures the room (actual state). When they differ it turns the heating on or off (sync) until they match. ArgoCD does exactly this for your cluster using git as the thermostat setting.

Mechanics

How it works

  • Manifests describing the cluster's desired state — Deployments, Services, ConfigMaps — are committed to git.
  • An ArgoCD Application points at a repository path and a target namespace or cluster.
  • The operator periodically polls git and the cluster, diffing desired state against actual state.
  • On any difference, sync applies the git manifests, and with auto-sync and self-heal enabled it reverts drift automatically.
  • Health status tracks the resources after sync so the UI and pipelines know the app is truly running, not just applied.

The GitOps loop: git is the source of truth, ArgoCD keeps the cluster in sync.

Git repository
ArgoCD operator
Drift detected?
Sync
Cluster
Healthy
Reference

Key commands

kubectl get applications -n argocd

List ArgoCD Applications and their sync and health status.

kubectl get applications web -n argocd -o yaml

Show the full desired and actual status of one application.

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

Expose the ArgoCD web UI locally.

argocd app sync web

Force a sync of an application from the CLI.

git log --oneline overlays/prod

See which commits changed the desired state for the environment.

Hands-on

Examples

An ArgoCD Application bound to a git repository

An ArgoCD Application bound to a git repository
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/acme/web-config.git
    path: overlays/prod
    targetRevision: main
  destination:
    server: https://kubernetes.default.svc
    namespace: prod
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

This Application tells ArgoCD to keep the prod namespace in sync with the overlays/prod directory of the config repo. auto-sync prunes deleted resources and self-heals drift, so the cluster always converges to what is committed.

Real world

In production

  • Config repositories hold per-environment overlays (dev, staging, prod) as separate paths or branches.
  • Promotion between environments is a pull request that changes which overlay is deployed — reviewed, merged, then synced.
  • Auto-sync with self-heal keeps clusters converged, while manual sync is preferred where blast radius matters.
  • CI writes artifacts (images, digests) to git, and the GitOps operator rolls them out — no cluster credentials in CI.
  • Multi-cluster setups register several destination clusters under one ArgoCD control plane.
Guidelines

Best practices

  • Keep secrets out of the repository; use sealed secrets, SOPS or an external secret operator.
  • Prefer one Application per deployable unit so blast radius and sync are easy to reason about.
  • Start with manual sync and approval, and only enable auto-sync when rollback is proven.
  • Use App-of-Apps to bootstrap many applications from a single git tree.
  • Record sync history and tag stable revisions so promotions and rollbacks are one-commit actions.
Watch out

Common mistakes

  • Committing plaintext secrets to the config repository.
  • Editing cluster resources directly, then watching self-heal silently overwrite the changes.
  • Pointing an Application at latest branches so desired state changes without review.
  • Letting CI push directly to the cluster, defeating GitOps's pull-based model and its security benefits.
Root cause analysis

Common issues

Error
Application stuck at OutOfSync
Root cause

The cluster drifted from git (manual edits) or the manifest in git is invalid.

Fix

Run argocd app diff web to see the differences, then sync; investigate why drift occurred before re-enabling self-heal.

Error
Sync fails with a resource not found error
Root cause

A manifest references a resource or namespace that does not exist yet.

Fix

Enable the CreateNamespace sync option and make sure required CRDs and namespaces are applied first.

Error
Application shows Degraded health
Root cause

A workload deployed but is not healthy — readiness probes failing or pods crash-looping.

Fix

Inspect the affected workload and fix the manifest in git, then sync.

When things break

Debugging tips

  • Check the Application's conditions and resource health in the Application YAML before anything else.
  • Compare the committed manifest with the live one to spot drift.
  • Look at the sync history for the last successful sync commit to see what changed.
  • Use argocd app diff to preview exactly what a sync would change before applying it.
Interviews

Interview checkpoint

Practice

Hands-on lab

Deploy an Application from Git with ArgoCD
40 min · advanced
In progress
Objectives
  • Verify cluster access with kubectl
  • Install ArgoCD into the cluster
  • Create an Application pointing at a git repository
  • Watch the application reconcile and reach Healthy status

Deploy an Application from Git with ArgoCD

40 min · advanced

0/6 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/3
1

In GitOps, what does an operator like ArgoCD do?

2

GitOps gives CI/CD pipelines direct credentials to push resources into the cluster.

3

A developer manually scaled a Deployment from 3 to 5 replicas, and ArgoCD reverted it to 3 minutes later. What explains this?

Quick reference

Cheat sheet

Core concepts
desired stateWhat git says should run
actual stateWhat the cluster currently runs
syncApply git manifests to converge
self-healAutomatically revert drift
healthActual runtime status after sync
ArgoCD operations
kubectl get applications -n argocdList apps and status
argocd app diff <app>Preview pending changes
argocd app sync <app>Trigger a sync
kubectl port-forward svc/argocd-server -n argocd 8080:443Open the UI
git log --oneline <env-path>Audit desired-state changes
Go deeper

Official documentation

ArgoCD documentation
docs
OpenGitOps specification
spec
ArgoCD Application specification
docs
Helm documentation
docs