GitOps and Declarative Deployment with ArgoCD: The Complete 2026 Guide

We deployed a service to production on a Tuesday morning. The deployment succeeded. The metrics looked good. By Wednesday afternoon, the service was down. The on-call engineer checked the logs: "The configuration was wrong. Someone manually updated the ConfigMap via kubectl apply." Who? When? Why? No audit trail. Git history showed nothing. Kubernetes showed everything. With GitOps and ArgoCD, the Git history IS the audit trail. Manual changes are detected and reverted automatically. The service never would have broken.

The Problem

Imperative infrastructure (using kubectl apply to make changes manually) is how most teams deploy today. An engineer runs a command. The cluster changes. No one else knows what happened. Another engineer runs a different command. The cluster drifts from the desired state. No record of why. Services break for mysterious reasons. Root cause analysis takes days. Rollback requires remembering what the old configuration was.

Why This Happens

Imperative deployments are immediate. kubectl apply. Done. Declarative deployments (GitOps) require discipline: every change must go through Git first. A pull request. Approval. Then ArgoCD syncs the Git state to the cluster. It takes more steps. Teams want speed. They bypass the process. They run kubectl apply directly. The cluster drifts. Chaos ensues.

The Solution — GitOps with ArgoCD

What GitOps Actually Means

Git is the source of truth. The cluster is a reflection of Git. If Git says the service should run 3 replicas, the cluster runs 3 replicas. If someone manually scales to 5, ArgoCD detects the drift and scales back to 3. The cluster is always reconciled to Git.

The ArgoCD Architecture

ArgoCD Agent: Runs in the cluster. Continuously watches the Git repository and the cluster state. When drift is detected (Git and cluster differ), ArgoCD syncs them.

Git Repository: Single source of truth. All infrastructure definitions (Kubernetes YAML, Helm charts) live here. Every change has a commit history. Every change requires approval.

Sync Behavior: Automatic or manual. Automatic means ArgoCD syncs immediately when Git changes. Manual means an engineer approves each sync.

Example: ArgoCD Application with Automatic Sync

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: payment-service
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/skillzmist/infrastructure
    targetRevision: main
    path: services/payment-service
    helm:
      values: |
        replicas: 3
        image:
          tag: v2.4.1
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true           # Delete resources not in Git
      selfHeal: true        # Sync if cluster drifts from Git
      allowEmpty: false     # Prevent accidental deletion
    syncOptions:
    - CreateNamespace=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m
  revisionHistoryLimit: 10  # Keep last 10 syncs for rollback

This ArgoCD Application tells ArgoCD: "Watch the Git repository at `services/payment-service`. If anything differs from the Git state, sync it automatically. Keep a history of the last 10 syncs so we can rollback if needed."

The GitOps Workflow

1. Make a change: Update the Deployment manifest in Git. Change replicas from 3 to 5. Commit and push.
2. ArgoCD detects the change: Within seconds, ArgoCD sees the Git commit.
3. Automatic sync: If automatic sync is enabled, ArgoCD applies the new manifest to the cluster immediately.
4. Audit trail: Git history shows who made the change, when, and why (commit message).
5. Rollback: If the change breaks something, revert the commit in Git. ArgoCD syncs back to the old state.

Example: Multi-Environment GitOps

# infrastructure/services/payment-service/kustomization.yaml
# Base configuration used by all environments

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: services

resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

commonLabels:
  app: payment-service
  team: backend

replicas:
  - name: payment-service
    count: 3

# infrastructure/overlays/staging/kustomization.yaml
# Staging-specific overrides

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

bases:
  - ../../services/payment-service

replicas:
  - name: payment-service
    count: 1  # Single replica in staging

images:
  - name: payment-service
    newTag: "v2.4.1-staging"

patches:
  - target:
      kind: ConfigMap
      name: payment-service-config
    patch: |-
      - op: replace
        path: /data/environment
        value: staging
      - op: replace
        path: /data/log_level
        value: debug

# infrastructure/overlays/production/kustomization.yaml
# Production-specific overrides

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

bases:
  - ../../services/payment-service

replicas:
  - name: payment-service
    count: 5  # High availability in production

images:
  - name: payment-service
    newTag: "v2.4.1"

patches:
  - target:
      kind: ConfigMap
      name: payment-service-config
    patch: |-
      - op: replace
        path: /data/environment
        value: production
      - op: replace
        path: /data/log_level
        value: info

Different environments (staging, production) are defined in separate Git directories. Each environment has its own Kustomize overlay with custom settings. A single Git repository manages all environments.

Benefits of GitOps with ArgoCD

1. Git is the audit trail: Every change has a commit, author, timestamp, and message. Compliance requirements met automatically.
2. Automatic drift detection: Manual kubectl apply is detected and reverted. The cluster stays in the desired state.
3. Easy rollback: Revert a Git commit. ArgoCD syncs back to the old state. Rollback takes seconds, not hours.
4. Multi-environment management: Single Git repository, multiple Kustomize overlays, different configurations per environment.
5. Disaster recovery: The entire cluster configuration is in Git. Recreate the cluster by pointing ArgoCD at the Git repository.

Common Mistakes to Avoid

1. Mixing imperative and declarative. If some engineers use kubectl apply and others use GitOps, drift happens. All changes must go through Git.
2. Automatic sync without review. Critical production changes should require approval via pull request, not auto-sync immediately.
3. No RBAC on the Git repository. If anyone can push to the infrastructure repository, anyone can deploy anything. Use branch protection and code review.
4. Storing secrets in Git. ArgoCD can sync secrets, but secrets should never be stored as plain text in Git. Use sealed-secrets or external-secrets.
5. Not testing changes before deploying. GitOps makes deployments fast, but you still need CI/CD validation of the Git commits before they get synced.

Key Takeaways

• GitOps makes Git the source of truth: Cluster state is always reconciled to Git.
• ArgoCD is the open-source standard for GitOps: Mature, battle-tested, used by thousands of teams.
• Automatic drift detection prevents misconfigurations: Manual kubectl apply is detected and reverted.
• Rollback is as simple as reverting a Git commit: No manual rollback procedures or cluster state guessing.
• Git history is your audit trail: Compliance, debugging, and root cause analysis are built-in.

Ready to implement GitOps with ArgoCD? The Skillzmist team has deployed ArgoCD for dozens of organizations. Reach out for a free technical consultation — we respond within 24 hours.

Related: How Platform Engineering Reduces CI/CD Complexity | GitOps Mistakes Teams Make