GitOps YAML Diff Checklist: Catch Dangerous Changes Before Merge
A green pipeline doesn’t mean the YAML means what you think. Use this checklist when reviewing Kubernetes, Helm, and CI diffs.
Part of the Technical Foundations series.
GitOps promised “merge to deploy.” It delivered that - including the ability to merge a one-character typo that points production at the wrong image tag. CI can tell you the YAML parsed. It rarely tells you the change is wise.
This checklist is what experienced reviewers skim for when the diff is mostly whitespace and two real landmines.
Prep the diff so humans can read it
Normalize ordering when keys thrash between revisions. Run the two versions through YAML Diff or a generic Diff Checker. Lint with YAML Linter before you argue about semantics - tabs vs spaces still waste lives.
Workload shape
- Replica counts and HPAs: accidental scale-to-zero, or scale-to-cost-explosion.
- Resource requests/limits: silent CPU starvation vs noisy-neighbor limits.
- Probe paths and timings: a wrong readiness probe equals perpetual Pending.
- Image digests vs floating tags:
latestin production is a future incident report.
Identity and secrets
- ServiceAccount changes and RBAC bindings - new verbs on secrets especially.
- Secret references that switched namespaces.
- Values files that suddenly inline credentials (reject; use sealed secrets or an external manager).
Traffic and policy
- Ingress hosts, TLS secrets, path rewrites.
- NetworkPolicies that open egress to the world “temporarily.”
- PodSecurity / securityContext bits flipped off for convenience.
CI/CD adjacent YAML
GitHub Actions and GitLab CI are GitOps cousins. Watch pull_request_target, wide permissions, and curl | bash installers. A workflow diff deserves the same suspicion as a Deployment.
Review ritual that fits in 10 minutes
- Skim the PR description for intent. If intent is missing, ask before deep-reading.
- Search the diff for
image:,replicas:,secret,ClusterRole,host:. - Compare rendered output when Helm or Kustomize is involved - raw template diffs lie.
- Require a plan for rollback (previous tag, previous revision in the GitOps app).
Render, then review
Helm and Kustomize diffs on templates lie by omission. Render to plain manifests in CI and diff the rendered output between base and PR HEAD. Reviewers should read the rendered Deployment, not only the values file that might expand wildly.
Store rendered artifacts as CI outputs for non-secret manifests. If secrets appear in rendered form, your packaging approach needs sealing or external references before you share artifacts broadly.
Blast radius questions
- Which clusters sync this path?
- Is there a progressive sync (app-of-apps, wave deploys)?
- What’s the rollback git revert plan, and who has merge rights to execute it?
- Did we change a shared library chart that affects thirty services?
Shared charts deserve stricter review than a single service values bump. Say that explicitly in CODEOWNERS.
Human noise versus real risk
Annotation churn and reordered keys create noisy diffs. Normalize in CI to reduce fatigue so reviewers still notice the image tag change hiding on line 400. Fatigue is a security problem, not just a UX problem.
Field notes from teams who shipped this
The pattern that keeps showing up: write the constraint first, then the steps, then the failure modes. Teams that only publish happy-path screenshots create tickets. Teams that document the ugly path create trust.
Schedule a short review ninety days after publishing. Check whether product UI names still match, whether linked tools still exist, and whether support still hears the same questions. Update the page or merge it. Standing still is how useful posts become interchangeable again.
If you adapt this article for internal wikis, keep the examples tied to your stack names. The moment you generalize back to “best practices for organizations,” you’ve started erasing the specificity that made the piece worth saving.
Secrets in GitOps without tragedy
Plain secrets in git are still a problem even when the diff looks small. Prefer sealed secrets, SOPS, or external secret operators. Reviewers should reject PRs that introduce base64-looking values in ConfigMaps that are actually credentials - yes, people still do that.
When a diff touches only Secret manifests, require a second reviewer from platform or security. Make that a CODEOWNERS rule, not a polite suggestion.
Test restores of secret material in non-prod. A GitOps repo that can’t recover credentials after a cluster rebuild is a paper fortress.
If you must temporarily break glass, open a ticket with an expiry, and schedule the cleanup merge before the incident chat scrolls away.
Announce risky merges
Image bumps to payments or auth services deserve a Slack heads-up with the rendered diff summary, not only a green check. Silence is fine for typo fixes in comments. Match the announcement energy to blast radius.
Keep a rolling “what we learned from bad YAML” doc. New hires read it faster than folklore.
When a merge coincides with a marketing launch, say so in the PR. Traffic spikes plus config changes are how small mistakes become dashboard-red afternoons. A one-line risk note beats a long silence.
Policy tests beside unit tests
Conftest or Kyverno tests in CI catch known-bad shapes: latest tags, missing resource limits, privileged pods. They’re not optional fluff once you’ve been burned. Start with five rules that match your last incidents, not a hundred theoretical ones.
FAQ
Should we auto-merge renovate bumps?
For non-prod, maybe. For prod image digests, prefer bundled PRs with smoke tests. Auto-merge without rendering is how surprises ship.
Where do OPA/Kyverno fit?
Great guardrails for known bad patterns. They don’t replace reading novel changes. Use both.