GitOps with Argo CD: A Clear First Example

You change a deployment file in Git, but the running app still has old settings. Someone fixes it by hand. Later, nobody remembers which version is right. GitOps helps by keeping the desired configuration in Git and comparing it with the running system.

This lesson uses the small Lecturre Kubernetes lab. First finish the Kubernetes guide. GitOps is useful when a team needs reviewed, repeatable changes. It still needs good access controls, tests and a recovery plan.

The idea in four steps

1. A person proposes a configuration change in Git.
2. Checks and reviewers examine it.
3. A controller reads the approved configuration and compares it with the cluster.
4. The controller reports the difference or applies it, depending on its settings.

Argo CD is one Kubernetes tool for this process. Flux is another. CI often tests code and builds images; GitOps commonly handles the desired deployment configuration. These jobs can work together.

What you need before this example runs

• A local practice cluster and the app files from the shared bundle.
• Argo CD already installed in that practice cluster, including its custom resource definitions.
• A Git repository containing the bundle's k8s directory. Replace the sample repository URL below.
• Permission for Argo CD to read the repository and manage the target namespace.

This lesson does not install Argo CD into an existing cluster. Follow its official installation guide for your chosen version and environment. Use a separate lab rather than a work cluster. Our local image is not in a registry: load lecturre-web:1.0 into the kind cluster first. A remote cluster would need a reachable registry image and appropriate access.

Describe the application

Save this as gitops-application.yaml after replacing YOUR_ORG and YOUR_REPO. The source path points at k8s, which holds the namespace and web app manifests. The destination address refers to the cluster where this Argo CD instance runs.

# Requires Argo CD installed in a learning cluster and a real accessible repo URL.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: lecturre-demo
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/YOUR_ORG/YOUR_REPO.git
    targetRevision: main
    path: k8s
  destination:
    server: https://kubernetes.default.svc
    namespace: lecturre-lab
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

This example uses manual sync. It does not enable automatic pruning or self-healing. The default Argo CD project is convenient for a lab; use a restricted project with approved repositories and destinations for a shared environment.

kubectl --context kind-lecturre-lab apply -f gitops-application.yaml

Apply this only after Argo CD is installed in the named local cluster and the repository is ready. If Kubernetes does not recognise kind Application, check that installation. Do not try to fix the error by changing the resource kind.

Review, then sync

Open your lab's Argo CD interface or use its CLI after logging in to that instance. Review the source repository, revision, destination and diff. Then sync the application. For a CLI session connected to the lab instance:

argocd app diff lecturre-demo
argocd app sync lecturre-demo
argocd app get lecturre-demo

A successful sync means the desired resources were applied. Health checks help show whether the app is ready. You still need a request test. Port-forward the web Service as shown in the Kubernetes guide and check /health.

Make one small change

Change APP_VERSION in the ConfigMap in Git, and change the Deployment's image tag to a new built version if you want a code release. Review and commit the change. For local kind, load the new image before syncing. Review the Argo CD diff and sync again.

Environment variables already read by a running Pod do not change when a ConfigMap changes. A new Pod must start to read them. For a config-only exercise, also change a Pod-template annotation such as lecturre.example/config-version from 1 to 2 in the Deployment. This creates a new rollout. Helm templates often use a configuration checksum for the same purpose.

Understand the settings before automating

Self-healing can change live resources back to the desired Git state. Pruning can delete resources removed from Git. Both can be useful, and both can surprise a team that has not agreed how changes work. Review deletion behaviour and access before enabling them.

If a release is wrong, review a revert to a known good configuration in Git and sync it. If self-healing is enabled, a manual live patch may be undone. A Git revert does not restore deleted data or reverse every database migration.

Common mistakes and a useful exercise

If the repository cannot be read, check the URL and repository access. If the app never becomes ready, inspect the Pods, image availability and health checks. If the controller cannot apply a resource, check its project rules and Kubernetes permissions.

Practice by changing the app version, reviewing the diff and reverting it. Write down which Git commit is desired and which image is running. That simple record is more useful than turning on every automation option at once.

Official references and further reading

Reviewed on 25 October 2026. Tools change, so check the official documentation for the version you use.

• Argo CD declarative setup
• Argo CD automated sync, pruning and self-healing
• Argo CD getting started

DevOps learning roadmap · All DevOps & Cloud tutorials