Is this tutorial up to date?

Yes. This tutorial was last reviewed and updated on June 2, 2026. We revisit popular DevOps & CI/CD tutorials regularly to keep them aligned with current best practices.

What level is this tutorial aimed at?

It is written for working developers with some backend experience. Beginners can still follow along, and senior engineers will find production-grade patterns and trade-off discussions.

Do I need to follow every step in order?

The walkthrough is sequential because each step depends on the previous one. If you only need a specific concept, the table of contents at the top of the article lets you jump straight to that section.

Where can I find the source code?

The full source code is available on GitHub: https://github.com/masterlabsystems/gitops-argocd-demo. Fork it, run it locally, and adapt it to your own project.

DevOps & CI/CD⏱ 6 min read·By Liyabona Saki·Published Jun 2, 2026

GitOps with ArgoCD — The Modern Kubernetes Deployment Strategy

A complete, production-grade guide to GitOps with ArgoCD on Kubernetes — workflow, architecture, multi-environment promotion, auto-sync, rollbacks and Spring Boot deployments.

The Fallacy of Push-Based CI/CD

The industry spent a decade perfecting Jenkins pipelines and GitHub Actions that execute kubectl apply -f or helm upgrade --install. We called it automation, but in reality, it was a fragmented series of imperative commands. The core problem with push-based deployment is the "drift gap." Once a pipeline finishes, the cluster is a black box. If an SRE manually edits a ReplicaSet or a Node failure triggers a rescheduling that conflicts with your manifest, your CI tool has no idea.

GitOps flips this by making the cluster pull the state. ArgoCD sits inside the Kubernetes control plane, acting as a continuous reconciliation loop. It treats your Git repository as the strict definition of reality. If Git says there are three replicas and the cluster has two, ArgoCD doesn’t wait for a webhook; it observes the state sub-optimally and forces a correction.

In a production environment with 50+ microservices, the "Success" green checkmark on a CircleCI job is a lie. It only means the command was sent. ArgoCD’s "Synced" and "Healthy" status marks the first time we’ve had true observability into the deployment lifecycle.

Architectural Topology: The Management Cluster Pattern

For serious scale, you do not install ArgoCD in Every. Single. Cluster. That creates a fragmented management nightmare. Instead, use a "Hub and Spoke" model. One hardened management cluster runs ArgoCD, which then assumes IAM roles or uses ServiceAccount tokens to manage worker clusters (Dev, Staging, Prod).

text

[ Git Repository ] <------- Webhook/Polling
      |
      V
[ ArgoCD (Hub Cluster) ] 
      |
      +------> [ Context: Dev-Cluster ] ----> (Namespace: app-alpha)
      |
      +------> [ Context: Staging-Cluster ] -> (Namespace: app-alpha)
      |
      +------> [ Context: Prod-Cluster ] ----> (Namespace: app-alpha)

This centralizes RBAC. You can grant developers ReadOnly access to the ArgoCD UI for Production while giving them Sync permissions in Dev, all from a single OIDC provider integration.

Evaluating Infrastructure-as-Code Patterns

In a GitOps workflow, how you structure your YAML is the difference between a 2:00 AM PagerDuty alert and a peaceful night. We evaluate three common patterns for organizing Kubernetes manifests against deployment velocity, dry-run safety, and multi-environment consistency.

The Plain Manifest Pattern This is the "Keep It Simple" approach. You store raw Kubernetes YAML files in directories named after environments (e.g., `/overlays/prod/deployment.yaml`).

* Deployment Velocity: High for small teams. No abstraction layers to learn. * Dry-Run Safety: Excellent. What you see is exactly what runs. * Multi-Environment Consistency: Poor. You end up copy-pasting 90% of your YAML between dev and prod, leading to "Configuration Drift" where a resource limit update is forgotten in one environment.

The Helm Chart Pattern The industry standard for packaging. You maintain a single chart and use `values.yaml` files for environmental overrides.

* Deployment Velocity: Moderate. Templating logic (if/else blocks in YAML) becomes a programming language of its own. * Dry-Run Safety: Moderate. You rely on helm template to debug, which often hides issues with underlying Kubernetes API versions. * Multi-Environment Consistency: High. The logic is centralized in the templates; only the data shifts.

The Kustomize Overlay Pattern The "Kubernetes Native" way. It uses a `base` layer and `overlays` that use strategic merge patches to modify specific fields.

* Deployment Velocity: High. No complex DSL or templating engine. It’s just YAML patching YAML. * Dry-Run Safety: Superior. ArgoCD has native support for Kustomize, allowing you to see a diff of the patched output before syncing. * Multi-Environment Consistency: High. It forces a clear inheritance model.

Selection Matrix for GitOps Manifest Management

Implementing the "Application of Applications" Pattern

In production, you don't manually create an ArgoCD Application for every microservice. That’s just clicking a different button instead of running a different command. You use the AppProject and Application CRDs to bootstrap your entire cluster state.

Here is a realistic Application manifest that targets a Spring Boot service using Kustomize. Note the automated sync policy—this is where true GitOps lives.

yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: billing-service-prod
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: finance-team
  source:
    repoURL: 'https://github.com/org/fin-microservices.git'
    targetRevision: HEAD
    path: apps/billing-service/overlays/production
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: billing-prod
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
      allowEmpty: false
    syncOptions:
      - Validate=false
      - CreateNamespace=true
      - PrunePropagationPolicy=foreground
      - PruneLast=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

The selfHeal: true flag is the critical component here. One hard-won lesson: we once found a developer who was manually scaling deployments to zero to "save costs" in a staging cluster. With selfHeal enabled, ArgoCD detected the manual kubectl scale within 30 seconds and scaled it back up to the Git-defined replica count. It effectively acts as a self-correcting immune system for your infrastructure.

Promotion Strategy: Trunk-Based vs. Environment Branches

A common mistake is using a staging branch and a production branch in Git. This leads to "Merge Hell" where cherry-picks are missed, and environments diverge.

Instead, use a single main branch with directory-based promotion. Your CI pipeline builds a Docker image, tests it, and then performs a "Git Write" to the manifest repository. It updates the image tag in /overlays/staging/kustomization.yaml. After automated integration tests pass in Staging, a simple PR moves that tag change to /overlays/production/kustomization.yaml.

This ensures that the exact same commit SHA that was tested in Staging is what progresses to Production. We found that shifting from branch-based promotion to Kustomize-image-tag-patching reduced our "Time to Deploy" from 22 minutes to under 7 minutes, as we eliminated the overhead of complex git merges.

Managing Secrets in a Transparent World

Since GitOps requires everything to be in Git, secrets become the primary blocker. NEVER commit base64 encoded secrets to Git. This isn't just a best practice; it's a fundamental requirement of the architecture.

The most robust approach is using the External Secrets Operator or Bitnami Sealed Secrets. With External Secrets, your Git repository contains a SecretStore reference (pointing to AWS Secrets Manager or HashiCorp Vault) and an ExternalSecret manifest. ArgoCD syncs the ExternalSecret manifest, and an operator inside the cluster fetches the actual sensitive value.

This decouples the "configuration of the secret" (which belongs in GitOps) from the "value of the secret" (which stays in a secure vault).

The Latency and Batching Reality

When you scale to hundreds of apps, ArgoCD's default polling interval (3 minutes) becomes a scaling bottleneck and a developer experience killer. Developers hate waiting 180 seconds for a change to reflect.

The solution is to implement GitHub/GitLab webhooks that notify ArgoCD instantly. However, there is a trade-off. In one high-traffic cluster, we saw the ArgoCD repo-server CPU usage spike to 100% when 50+ developers were pushing small commits simultaneously.

The Fix: We implemented a 500ms commit batching delay at the ingress level and tuned the timeout.reconciliation setting. By increasing the reconciliation busyness but optimizing the parallelismLimit in argocd-cm, we dropped our p99 deployment latency (time from git push to pod starts) from 480 seconds (pure polling) to 90 seconds (webhook + optimized reconciliation).

Sharp Takeaway for Platform Teams

GitOps with ArgoCD is not about replacing kubectl. It is about moving the "Source of Truth" from the mind of an engineer or the transient state of a CI runner into a versioned, auditable repository.

If you are just starting, ignore Helm for your internal apps. Start with Kustomize overlays and a centralized management cluster. The complexity of Helm's Go-templating is a tax you don't need to pay until you are distributing software to third parties. Your priority should be selfHeal and prune—these are the features that ensure your cluster state is a reflection of your intent, rather than a collection of historical accidents. The ultimate goal is a cluster where you could delete every namespace, and ArgoCD would rebuild the entire business state in minutes without a single manual command.

Trade-offs of GitOps vs push-based deploys

GitOps (ArgoCD, Flux) promises a single source of truth and automatic reconciliation. It also introduces trade-offs a push-based pipeline avoids. Wins: the cluster state matches Git by construction; drift is detected and (optionally) reverted; a rollback is a git revert; audit is free. Costs: deploy latency goes up — the controller polls or watches, and 'my commit landed' to 'my pod is running' takes 30s–2min longer than a direct kubectl apply. Debugging why a sync failed adds one layer: it is now the controller's job to tell you, not the pipeline's. Emergency access — the manual kubectl you would use during an incident — fights the reconciler unless you know how to pause it. Secrets management is more work: you cannot commit them to Git, so you need Sealed Secrets, SOPS or an external secrets operator. GitOps wins clearly for multi-cluster fleets and regulated environments; single-cluster teams often stay happier with a good CI-based push.

Go deeper