Before deploymentgitops-repo-review

GitOps Repository Review Checklist

15 items ·7 critical ·7 warn ·1 info

How to use this checklist

This is what the GitOps repository itself is expected to look like, independent of the controller that consumes it. A repo that passes this list will deploy predictably through any conforming GitOps controller; one that fails it will surprise whichever controller ends up reading it.

Use it during repository design and again whenever the layout is about to change. Repo restructuring is the operation that most often breaks GitOps pipelines, so this list is also the regression check before such a change lands.

Sign-off

Every critical item must pass. A failing critical item blocks the repository from being a source of production state; it is not a note for later. Record the date, the reviewer, and the disposition of every item that did not pass.

Critical7 items

The GitOps repository has a single stated purpose (cluster bootstrap, application config, environment overlays). Application source code and CI pipelines do not live alongside manifests they deploy.
Environments are isolated by directory (`clusters/prod/`, `clusters/staging/`, `apps/<name>/base|overlays/`) and not by branch. Production state is reachable without a checkout of staging.
```
find . -maxdepth 4 -type d | sort | head -40
```
Every image reference in the GitOps repo is a digest (`@sha256:...`) or a versioned tag pinned in a values file that the controller reconciles. `latest` is not present in any rendered manifest.
```
grep -RIn "image:" apps/ overlays/ clusters/ 2>/dev/null | grep -E "(:latest|@sha256:)" | head; echo "---"; grep -RInE ":\s*latest" apps/ overlays/ clusters/ 2>/dev/null | head
```
Manifests in the GitOps repo are validated in CI: `kubeconform`, `kubeval`, `helm lint`, `kustomize build`, OPA / Conftest against policy. A merge that breaks a manifest cannot reach the controller.
OPA / Kyverno / Conftest policies are evaluated against every change in CI, and policy violations block the merge. The policies are the same ones enforced by the cluster's admission controllers.
A documented promotion flow exists: dev → staging → production, expressed as a Git change (PR) and a controller sync. Promotion is not a manual `kubectl apply`.
The branch or directory that represents production state is protected: direct pushes blocked, CODEOWNERS enforced, and any change requires an approval. `argocd app sync` against an unprotected branch is a finding.

Warning7 items

No resource exists in the GitOps repo that is not referenced by an Application / Kustomization / HelmRelease. A manifest that is "just sitting there" is either dead code or a future incident.
Manifests do not contain hard-coded production URLs, account IDs, or domain names that should be templated. A GitOps repo whose values change per environment is mis-architected; one whose manifests change per environment is worse.
Multi-cluster / multi-tenant deploys are expressed as an ApplicationSet (Argo CD) or Kustomization template (Flux), not as a hand-maintained list of Applications. The list is generated, not curated.
Helm charts installed by the GitOps controller are sourced from a controlled registry or path, not from `helm template` output checked into the repo. The repo holds parameters, not rendered manifests.
Image updates flow through a controlled mechanism (Argo CD Image Updater, Flux Image Automation, Renovate with GitOps pull-request flow) rather than by hand-editing the manifest.
Production sync windows (or app-projects-equivalent) are configured so that production does not accept sync outside the agreed windows. A change attempted outside the window is held, not silently applied.
Every change to the GitOps repo records the author, the commit, the pipeline run that validated it, and the merge approval. The trail is queryable; "who changed this" is answerable in under five minutes.

Info1 item

Each application directory has a short README explaining what it deploys, who owns it, the rollback path, and the on-call rota. A repo that requires tribal knowledge to operate is mis-owned.