What are the limitations and anti-patterns of GitOps?

GitOps is powerful but not a universal solution. Being aware of its genuine limitations prevents teams from forcing it into contexts where it creates more friction than value.

Genuine limitations:

• Secret management adds complexity: Every team member must understand at least one secret management tool (SOPS, Sealed Secrets, ESO). There is no "just commit the secret" escape hatch. Onboarding engineers to this mental model takes real effort.
• Stateful workloads need careful design: Databases, message brokers, and anything with persistent state require ordered operations (migrations, backup/restore, leader election) that don't map naturally to declarative reconciliation. GitOps doesn't replace operational runbooks for stateful services.
• Slow emergency response path: When a production incident requires an immediate replica-count change, the fastest GitOps response is still: edit file → commit → push → wait for operator poll cycle. Teams must define "break-glass" procedures (e.g., temporarily pausing the operator's selfHeal to allow direct kubectl) without abandoning the GitOps principle entirely.
• Git history pollution: Automated image-tag updates generate many tiny commits. Over time the commit log becomes noisy and hard to scan. Mitigate with squashing, dedicated automation commits, or Flux's imageTemplate commit message customisation.
• Learning curve: Teams unfamiliar with Kubernetes CRDs find GitOps reconciliation errors hard to debug — "why is my Kustomization not Ready?" is a different mental model from "why is my pipeline failing?"

Anti-patterns to avoid:

• Storing unencrypted Kubernetes Secrets in Git (even base64 is cleartext).
• Running kubectl apply directly on a GitOps-managed cluster — the operator will revert it, causing confusion and potential incidents.
• Using mutable image tags (:latest) — breaks the traceability between Git commit and deployed artefact.
• Keeping source code and deployment manifests in the same repository — CI rebuilds trigger on code changes and GitOps changes become entangled.
• Not pinning Helm chart versions — an upstream chart update can unexpectedly change a production deployment.