Stackbook Logo
deploymentestablished · medium operational burden

GitOps

Also known as: git-driven-operations, pull-based-deployment

Intent

Make a Git repository the single source of truth for desired system state, with an agent continuously reconciling the live environment to match it.

Problem

Deployments driven by CI scripts that push changes into clusters leave no record of what is actually running, require broad credentials in the pipeline, and drift silently when someone edits the environment by hand. Rollbacks and audits become archaeology.

Forces

  • •Desired state must be auditable and reviewable
  • •Cluster credentials should not live in CI systems
  • •Manual changes cause configuration drift
  • •Rollback must be fast and predictable

Solution

Overview

GitOps treats Git as the control plane. Instead of a pipeline running kubectl apply against production, a controller inside the cluster watches a repository and makes reality match it. Every change is a commit, which gives review, attribution and history for free.

How it works

The CI pipeline builds and tests an image, then opens a commit in the config repository that bumps the image tag. A reconciler pulls that repository on an interval or webhook, renders the manifests, diffs them against the live cluster and applies the delta.

app repo --CI--> image registry
                    |
config repo <-- commit: tag bump
     ^
     | pull
 reconciler (in cluster) --apply--> live state
     |
     +-- drift detected --> revert or alert

Rollback is reverting the commit; the reconciler converges to the previous state.

Pitfalls

  • Committing plain secrets. Use sealed secrets, SOPS or an external secret operator.
  • One repository branch for all environments, which turns every merge into a production deploy. Use directories or branches per environment with explicit promotion.
  • Automatic pruning enabled without safeguards, deleting resources that were created out of band.
  • Ignoring reconciler health. If it is down, drift accumulates unnoticed, so alert on sync failures and age of last successful sync.
  • Treating Git latency as acceptable during incidents without a documented break-glass path.

Key takeaways

  • Git holds desired state, the cluster pulls it, and drift gets corrected.
  • Rollback and audit become ordinary Git workflows.
  • Keep application code and environment config separate.
  • Solve secrets and promotion before adopting it widely.
  • Monitor the reconciler as production infrastructure.

✓ When to Use

  • •Kubernetes or other declarative platforms with many environments
  • •Teams needing audit trails and pull-request approval for production changes
  • •Fleets of clusters that must stay consistent

✗ When Not to Use

  • •Imperative systems with no declarative representation
  • •Tiny single-environment projects where a script suffices
  • •Secrets handling is unsolved and would end up in plain Git

Pros

  • +Full audit trail and trivial rollback via git revert
  • +Credentials stay inside the cluster
  • +Drift is detected and corrected automatically

Cons

  • −Secrets need a separate mechanism
  • −Promotion across environments needs extra tooling
  • −Eventual consistency makes deploy status less immediate

Cost Profile

Infrastructure

Low - reconciler runs in each cluster

Operational

Medium - repository structure and reconciler upkeep

Cognitive

Medium - pull model and repo layout conventions

Failure Modes

  • Reconciler outage freezes all deployments

  • Autosync applies a bad commit across every cluster at once

  • Hotfix by hand is reverted by the reconciler mid-incident

Real-World Examples

Alternatives

  • deployment-strategies

Related Patterns

  • kubernetes-patterns
  • platform-engineering

Competency Domains

reliability opssecurity compliance