Disclosure: Some links in this article are affiliate links. We may earn a small commission at no extra cost to you.

GitOps Best Practices for Kubernetes in 2026: Lessons from Production

GitOps sounds simple — “just put everything in Git.” In practice, teams learn hard lessons about repository structure, secret management, and deployment strategies. Here are the best practices that separate smooth GitOps operations from painful ones.

Repository Strategy

Separate App Code from Config

Don’t: Keep Kubernetes manifests in the same repo as application code.

Do: Use separate repositories:
– my-app — application source code, Dockerfiles, tests
– my-app-config — Kubernetes manifests, Helm values, Kustomize overlays

Why: Application commits (code changes) and config commits (scaling, environment variables) have different cadences and review requirements. Mixing them creates noisy Git history and complicated CI/CD triggers.

Mono-Repo vs Multi-Repo

Approach	When to use	Trade-offs
Mono-repo	Small teams, few services	Simpler to manage, harder to scale RBAC
Multi-repo	Large orgs, many teams	Better isolation, more repos to manage
Hybrid	Most teams	App-config in one repo, infra in another

Recommended structure (mono-repo):

k8s-config/
├── apps/
│   ├── frontend/
│   │   ├── base/
│   │   └── overlays/
│   │       ├── staging/
│   │       └── production/
│   └── api-server/
│       ├── base/
│       └── overlays/
├── infrastructure/
│   ├── cert-manager/
│   ├── ingress-nginx/
│   └── monitoring/
└── clusters/
    ├── staging/
    └── production/

Environment Promotion

Pattern: Branch-per-Environment (Avoid)

Don’t use staging and production branches. Cherry-picking between branches is error-prone and creates divergence.

Pattern: Directory-per-Environment (Recommended)

Use Kustomize overlays or Helm values files:

# base/deployment.yaml (shared)
apiVersion: apps/v1
kind: Deployment
spec:
  replicas: 1

# overlays/staging/kustomization.yaml
patchesStrategicMerge:
  - replicas-patch.yaml

# overlays/production/kustomization.yaml
patchesStrategicMerge:
  - replicas-patch.yaml  # replicas: 3

Promotion Flow

Developer PR → merge to main → staging auto-syncs
  ↓ (after validation)
Promotion PR → update production overlay → production auto-syncs

Secret Management

Rule #1: Never store secrets in Git. Not even encrypted secrets without a proper tool.

Options (ranked by maturity)

Tool	Complexity	Best for
Sealed Secrets	Low	Small teams starting out
External Secrets Operator	Medium	Teams with existing vaults
SOPS + Age	Medium	Encrypted-in-Git approach
HashiCorp Vault	High	Enterprise, compliance

Sealed Secrets Example

# Install Sealed Secrets controller
helm install sealed-secrets -n kube-system sealed-secrets/sealed-secrets

# Encrypt a secret
kubectl create secret generic db-creds \
  --from-literal=password=supersecret \
  --dry-run=client -o yaml | \
  kubeseal --cert cert.pem -o yaml > sealed-secret.yaml

# The sealed secret is safe to commit to Git
git add sealed-secret.yaml
git commit -m "add encrypted db credentials"

Deployment Strategies

Progressive Delivery with Argo Rollouts

ArgoCD integrates with Argo Rollouts for canary and blue-green deployments:

apiVersion: argoproj.io/v1alpha1
kind: Rollout
spec:
  strategy:
    canary:
      steps:
        - setWeight: 20
        - pause: {duration: 5m}
        - setWeight: 50
        - pause: {duration: 5m}
        - setWeight: 80
        - pause: {duration: 5m}

Rollback

The beauty of GitOps — rollback is just git revert:

git revert HEAD
git push
# ArgoCD automatically syncs to the previous state

Monitoring Your GitOps Pipeline

ArgoCD Metrics

ArgoCD exposes Prometheus metrics at :8082/metrics:

# Key metrics to alert on
argocd_app_sync_total{phase="Error"}     # Sync failures
argocd_app_health_status{health="Degraded"}  # Unhealthy apps
argocd_git_request_duration_seconds      # Git fetch latency

Dashboard

ArgoCD’s built-in UI shows sync status, but for a production overview, build a Grafana dashboard with these panels:
– Sync success rate by application
– Time between Git push and deployment
– Number of OutOfSync applications
– ArgoCD resource usage

Common Mistakes

No PR reviews for config changes — config is code, review it
Manual kubectl edits — ArgoCD will revert them (that’s the point)
Too many apps in one ArgoCD instance — 300+ applications need tuning
Not testing manifests in CI — use kubeval, kustomize build, or helm template in your CI pipeline
Ignoring sync waves — deploy CRDs and operators before the apps that need them

Let's Talk DevOps