Argo CD is configured with Kubernetes resources like everything else in the cluster. The core one is Application: it says “take the manifests at this path in this repository and keep them applied to this cluster and namespace”. This guide creates a small configuration repository, registers it with an Application, and then changes Git to see the sync happen. It assumes Argo CD is installed and you can sign in (see the previous guide).

Prepare a configuration repository

Create a Git repository (any host Argo CD can reach) with this layout:

webapp-config/
├── application.yaml      # the Argo CD Application, applied once by hand
└── dev/
    ├── deployment.yaml
    └── service.yaml

dev/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: webapp
  template:
    metadata:
      labels:
        app: webapp
    spec:
      containers:
        - name: webapp
          image: nginx:1.25
          ports:
            - containerPort: 80

dev/service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: webapp
spec:
  selector:
    app: webapp
  ports:
    - port: 80
      targetPort: 80

The manifests deliberately omit a namespace. Argo CD applies them into the destination namespace you configure next. Keep application.yaml outside the synced path (dev/) so the application doesn’t try to manage its own definition. If the repository is private, add credentials under Settings → Repositories in the UI first.

Write the Application manifest

application.yaml:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: webapp-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/webapp-config.git
    targetRevision: HEAD
    path: dev
  destination:
    server: https://kubernetes.default.svc
    namespace: webapp
  syncPolicy:
    syncOptions:
      - CreateNamespace=true
    automated:
      prune: true
      selfHeal: true

The parts that matter:

• source is where the desired state lives: the repository, the revision to track (HEAD follows the default branch), and the folder inside it.
• destination is where it gets applied. https://kubernetes.default.svc means “the cluster Argo CD itself runs in”. Managing an external cluster means registering it and using its API server address instead.
• project: default puts the app in Argo CD’s built-in project. Projects group applications and restrict what they may deploy.
• syncPolicy turns on automatic sync and creates the namespace if it doesn’t exist. What prune and selfHeal do gets its own guide. Check the apiVersion against the current docs, since it’s the field most likely to change between releases.

Register the application

Commit and push the repository, then apply the manifest to the cluster once:

kubectl apply -f application.yaml

This is ideally the last time you run kubectl apply for this application. From here on, changes go through Git.

Explore the resource tree

Open the UI. The webapp-dev application appears and, within a few seconds, moves to Synced and Healthy. Open it to see the resource tree: the Service, the Deployment, the ReplicaSet behind it, and two Pods. Selecting a resource shows its live manifest, events, and (for Pods) logs, which is often quicker than switching to the terminal. Confirm from the cluster too:

kubectl get all -n webapp

Change Git and watch it sync

Edit dev/deployment.yaml in your repository, changing the image tag to nginx:1.26, and commit to the tracked branch. Argo CD polls repositories every three minutes by default, so either wait, or click Refresh on the application to make it check right away. The application briefly shows OutOfSync, then a new ReplicaSet rolls out. Verify the change landed:

kubectl get deploy webapp -n webapp \
  -o jsonpath='{.spec.template.spec.containers[0].image}'; echo

That is the whole loop: edit Git, Argo CD converges the cluster. The next guide covers how to control that behavior.