GitOps Adoption Framework

GitOps makes Git the single source of truth for what should be running. An agent inside the environment pulls the declared state and makes reality match it, so the path to production is a reviewed commit rather than a privileged command.

How it works

CI builds and tests the application, pushes an image tagged with the commit hash, and opens a change in the config repository that updates the image reference. After review and merge, the reconciler detects the new commit, renders manifests and applies the difference to the cluster. It reports health and sync status, and flags or reverts manual changes made outside Git.

A phased rollout reduces risk. Begin in a non-production cluster with the reconciler in report-only mode so teams can see the drift it detects without anything being changed. Next enable automatic sync for staging, then production with manual approval, and finally self-healing once trust is established. Keep the configuration repositories small and well owned, because pull request review is the main control in the model, and slow or rubber-stamped reviews quietly remove the safety the approach is meant to provide.

Implementation steps

1. Choose a reconciler such as Argo CD or Flux and install it per cluster.
2. Create an environment repository with a directory per environment, using Kustomize or Helm for shared bases.
3. Move one low-risk service first and prove the full cycle including rollback.
4. Restrict direct cluster write access to the reconciler and an audited break-glass role.
5. Adopt a secrets approach such as sealed secrets or an external secrets operator.
6. Define promotion: automated pull request from staging to production after checks pass.
7. Add notifications for sync failures and drift.

Pitfalls

• Committing plain secrets to Git.
• Using mutable image tags like latest, which hides what is deployed.
• Enabling auto-prune on day one without understanding what will be deleted.
• Mixing application source and environment config, causing noisy history and loops.
• No documented break-glass path, leading teams to bypass the process.

Metrics to watch

• Deployment frequency and lead time from merge to running.
• Drift events detected per week.
• Sync failure rate and time to recover.
• Percentage of workloads managed through Git.
• Number of manual production changes using break-glass access.

Example Argo CD application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: checkout-prod
  namespace: argocd
spec:
  project: production
  source:
    repoURL: https://git.example.com/platform/env-config.git
    targetRevision: main
    path: environments/prod/checkout
  destination:
    server: https://kubernetes.default.svc
    namespace: checkout
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Key takeaways

• If it is not in Git, it is not the desired state.
• Pull-based reconciliation removes production credentials from CI.
• Solve secrets and promotion design before scaling out.
• Keep an audited emergency path so the process is not bypassed.