GitOps Overview

What this section covers

This series explains one decision: Git is the source of truth for what runs. ArgoCD runs inside the cluster, reads Git, and keeps the cluster matched to the repo. That means “what is running?” should always have the same answer as “what is in Git?”

That decision drives every process below:

• no environment branches,
• no manual cluster changes,
• no release ambiguity,
• no direct version guessing.

Why this is the operating model

Traditional deploy flows often split the code change, the deploy command, and the live result across different tools. That makes it harder to know what really changed and how to undo it. Here, the change is written to Git first, then ArgoCD applies it. That gives engineers one place to inspect, review, and roll back runtime state.

How it flows

flowchart LR
    Developer(("Developer")) --> PR["Open PR"]
    PR --> Reviewer(("Reviewer"))
    Reviewer --> Main["Merge to main"]
    Main --> RM(("Release Manager"))
    RM --> Argo["ArgoCD reconciles"]
    Argo --> Cluster["Cluster matches Git"]

    style Developer fill:#dbeafe,stroke:#2563eb,color:#172554
    style Reviewer fill:#fef3c7,stroke:#d97706,color:#451a03
    style RM fill:#ede9fe,stroke:#7c3aed,color:#2e1065

The three colored circles are the people: blue Developer, amber Reviewer, purple Release Manager. Every neutral box is a system or step. Read the colors first to see who acts, then follow the arrows left to right to see what happens.

The model in one glance

1. Developer makes a focused change on a branch.
2. PR is reviewed and merged to main.
3. A release commit is created when an environment needs to move.
4. ArgoCD applies that commit-defined state.
5. Drift is corrected automatically; rollback is a new Git commit.

What this lets teams do

• Promote one immutable image across test, staging, and prod.
• Keep security and access checks central to GitHub and ArgoCD.
• Keep incident response repeatable: recover with a forward Git change first.

Common concern this solves

Most teams avoid short-lived main deployment because they fear no rollback and noisy deployments. GitOps solves both: every release is a reversible commit and every environment comes from declared state, not ad-hoc cluster commands.

What is in this section

• Commit Messages — format for predictable releases
• Branch Protections — branch rules, rulesets, and GitHub governance enforcement
• Pull Requests — controlled merge gates
• Code Review — review posture and decisions
• Release Strategy — version and channel model
• Environments — files, not branches
• Deployments — end-to-end flow, roles, and feature flags
• Roll Forward Recovery — recovery through Git, not manual cluster edits
• Road to Production — secure delivery from PR to production

Related topics moved to their canonical homes: Ownership and Systems owns role expectations, Incident Response owns incident handling and priority, and Security Compliance owns dependency and supply-chain remediation.

Automation

Automation should make the GitOps path easier to follow, not create a second path. Good automation opens PRs, runs checks, creates preview environments, syncs ArgoCD, posts alerts, and collects evidence. Human approval remains required for production promotion, emergency overrides, and any decision that changes risk.

Where enforcement happens

GitHub rulesets and governance scripts block unsafe merges. ArgoCD enforces desired state. LaunchPad writes release state transitions. The reusable script source lives in templates/governance/, and repos that need the command surface should use templates/taskfiles/Taskfile.governance.yml. Together, they make process correctness repeatable.