Add blog post: GitOps Best Practices I Wish I Had Known Before

[dirien]

Summary

• New blog post: "GitOps Best Practices I Wish I Had Known Before" covering 16 battle-tested GitOps best practices
• Covers repo structure, drift detection, secret management, progressive delivery (including Kargo), the IaC-to-GitOps bridge pattern, rendered manifests pattern, and pragmatic deviations at scale
• Includes code examples (Kustomize directory structure, GitHub Actions CI pipeline, ArgoCD ignoreDifferences, ExternalSecret CR, gitops-bridge ConfigMap)
• References real-world production stories from Intuit (20K apps, 200 clusters), Statsig (Pulumi + ArgoCD), and a German automotive FluxCD deployment
• Author: Engin Diri

Test plan

• Verify make build passes
• Verify blog post renders correctly with make serve
• Check all internal and external links resolve
• Verify Hugo shortcodes render (notes, figure, youtube, related-posts, cta-button)
• Verify meta image displays in social preview

[claude]

Documentation Review

Thanks for this comprehensive GitOps best practices blog post, @dirien! This is a solid piece with great depth, practical examples, and real-world production stories. I've reviewed the content and have several suggestions for improvement.

---

Issues Found

1. Image Format Issue (Line 69, gitops-meme.png)

The file gitops-meme.png is actually a WebP image, not a PNG. This may cause rendering issues:

gitops-meme.png: RIFF (little-endian) data, Web/P image, VP8 encoding

Suggestion: Convert the WebP file to an actual PNG format, or rename it to .webp and update the reference in line 69.

---

2. Spelling/Grammar Issues

Line 44: "can feel like trying to herd cats through a YAML factory while the factory is on fire"

• The phrase "while the factory is on fire" is added here but not in the LinkedIn social snippet (line 38). Consider consistency.

Line 161: "kustomization.yaml # replicas: 3, limits: 1Gi"

• Space formatting: Should use consistent spacing in comments across all three examples (lines 156, 158, 161)

Line 189: "the number one cause of failed deployments was missing PR reviews"

• This is a strong claim. Consider adding "according to [source]" or "in their experience" for attribution.

Line 240: "This gives reviewers a concrete view"

• Style note: Consider "provides" instead of "gives" for more professional tone.

Line 262: "build your exclusion lists before you turn on auto-sync, not after"

• Good advice! This is clear.

---

3. Link Verification

All internal links appear to use correct anchor format. However, verify these external links are current:

• Line 48: OpenGitOps link (https://opengitops.dev/)
• Line 105: ArgoCD link (https://argoproj.github.io/cd/)
• Line 105: FluxCD link (https://fluxcd.io/)
• Line 121: ArgoCD best practices (https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/)
• Line 143: Akuity rendered manifests pattern (https://akuity.io/blog/the-rendered-manifests-pattern)
• Line 143: ArgoCD source hydrator docs
• Line 143: Kargo Render GitHub link
• Line 210: Conftest link (https://www.conftest.dev/)
• Line 210: Kyverno link (https://kyverno.io/)
• Line 294: Kargo link (https://kargo.io/)
• Line 322: Sealed Secrets link (https://sealed-secrets.netlify.app/)
• Line 324: SOPS GitHub link
• Line 356: gitops-bridge GitHub link
• Line 360: Statsig blog link
• Line 408: Prometheus and Grafana links

---

4. Style Guide Compliance

Capitalization (proper nouns vs common nouns):

The post correctly uses lowercase for common terms like "stack" throughout. Good adherence to the style guide.

Headings:

• H1 (title): "GitOps Best Practices I Wish I Had Known Before" ✓ Title Case
• H2 headings: All correctly use sentence case ✓

Callout boxes:

All use {{% notes type="info" %}} correctly ✓

---

5. Content Accuracy

Line 93: "A caveat though: this works cleanly for stateless, declarative resources..."

• Excellent nuance! This caveat is important and well-placed.

Line 110-113: Discussion of webhook receivers

• Great practical advice. This addresses a real pain point at scale.

Line 143: Rendered manifests pattern

• Good clarification distinguishing this from the branch-per-environment anti-pattern.

Line 211: Warning about SOPS with rendered manifests

• Important security consideration. Well done.

Line 262: Auto-remediation exclusions

• The example in lines 268-279 is clear and practical.

Line 324: SOPS description

• Line 324 mentions "SOPS + age" but the description could be clearer. Consider: "encrypts secret values in-place within your YAML files, so you can commit encrypted secrets directly to Git"

---

6. Code Examples

Lines 147-163: Directory structure example

• Clear and well-formatted ✓

Lines 215-237: GitHub Actions workflow

• Practical example ✓
• Note: kubeval is archived. Consider mentioning alternatives like kubeconform in a note.

Lines 268-279: ArgoCD ignoreDifferences example

• Correct YAML syntax ✓
• Good use of both jsonPointers and jqPathExpressions

Lines 328-344: ExternalSecret example

• Correct CRD syntax ✓

Lines 365-379: gitops-bridge ConfigMap example

• Clean example ✓

---

7. Frontmatter Validation

title: ✓ Present and descriptive
date: ✓ 2026-02-11 (future date is fine for scheduled posts)
draft: ✓ false
meta_desc: ✓ Present and under 160 characters
meta_image: ✓ meta.png exists
authors: ✓ engin-diri exists in data/team/team/
tags: ✓ Appropriate tags (gitops, kubernetes, best-practices, argocd, devops)
social: ✓ Twitter and LinkedIn snippets provided

---

8. Shortcodes

All shortcodes appear correctly formatted:

• {{< youtube "OhFdLTU5sAo?rel=0" >}} ✓
• {{< related-posts >}} ✓
• {{< blog/cta-button ... >}} ✓ (3 instances)
• {{< figure ... >}} ✓
• {{% notes type="info" %}} ✓ (multiple instances)

---

9. SEO and Readability

Title: Clear and keyword-rich ✓

Meta description: Good summary that includes key terms ✓

Structure: Well-organized with clear numbered sections ✓

Paragraph length: Most paragraphs are appropriately concise. A few could be split:

• Lines 121-127 (7 sentences) - consider splitting at "Either way"
• Lines 254-259 (5 sentences) - this is fine

Call-to-action: Clear CTAs at the end ✓

---

Suggestions for Enhancement

1. Add a "TL;DR" or "Key Takeaways" section at the top after the introduction, before the numbered list begins. This helps readers quickly scan the value proposition.

2. Consider adding timestamps or update dates for the production stories (Intuit, Statsig, German automotive manufacturer) so readers know how current these examples are.

3. Line 324 (SOPS description): Clarify that SOPS encrypts values in-place vs. sealed-secrets which creates a separate CRD. The current description could be more precise.

4. Line 208 (kubeval): Add a note that kubeval is archived and mention kubeconform as the maintained alternative:

   - name: Validate YAML schemas
     run: kubeconform --strict environments/**/*.yaml
   

5. Consider adding a comparison table in section 13 showing the trade-offs between different secret management approaches (External Secrets Operator vs Sealed Secrets vs SOPS vs Pulumi ESC).

---

Summary

This is a high-quality, comprehensive blog post that demonstrates deep production experience with GitOps. The writing is engaging, the examples are practical, and the advice is sound. The main actionable item is converting the gitops-meme.png file to an actual PNG format. The other suggestions are minor improvements.

Recommendation: Approve after fixing the image format issue.

---

Mention @claude if you'd like me to review any revisions or if you have questions about any of these suggestions!

[pulumi-bot]

Your site preview for commit 65f2af0 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-17468-65f2af06.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit 7219840 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-17468-72198401.s3-website.us-west-2.amazonaws.com.

[claude]

Documentation Review

I've completed a review of this GitOps best practices blog post. The content is comprehensive, well-structured, and provides valuable production insights. Here are my findings:

✅ Strengths

• Excellent structure: 16 well-organized best practices with clear navigation
• Strong technical depth: Real production examples from Intuit (20K apps, 200 clusters), Statsig, and German automotive FluxCD deployments
• Practical code examples: GitHub Actions workflow, Kustomize structure, ArgoCD config, ExternalSecret manifest
• Good engagement: Drake meme, YouTube embed, conversational tone appropriate for blog
• Proper frontmatter: All required fields present (title, date, meta_desc, meta_image, authors, tags, social)
• Author verified: engin-diri exists in data/team/team/engin-diri.toml

📝 Issues Found

Critical: Missing trailing newline (line 445)

The file must end with a newline character per AGENTS.md requirements.

{{< blog/cta-button "Pulumi Kubernetes Operator" "/docs/iac/guides/continuous-delivery/pulumi-kubernetes-operator/" >}}

Style: Heading capitalization issues

Per STYLE-GUIDE.md, H2+ headings should use sentence case, not title case. The following headings need adjustment:

Line 79: "Git is your single source of truth (no, really)" ✅ Correct

Line 93: "Declarative over imperative, always" ✅ Correct

Line 107: "Pull-based deployments are the way" ✅ Correct

Line 125: Should be "Separate app code from deployment config (when it hurts not to)" (already correct)

Line 141: Should be "Use directories, not branches, for environments" (already correct)

Line 179: Should be "Trunk-based development or bust" (already correct)

Line 195: Should be "Every change gets a PR review (no exceptions)" (already correct)

Line 210: Should be "Validate before you merge" (already correct)

Line 251: Should be "Tag with commit SHAs, not 'latest'" (already correct)

Line 263: Should be "Automate drift detection and reconciliation" (already correct)

Line 292: Should be "Progressive delivery: don't YOLO to production" (already correct)

Line 310: Should be "Policy-as-code: your automated guardrails" (already correct)

Line 323: Should be "Secrets don't belong in Git (ever)" (already correct)

Line 367: Should be "Bridge your IaC and GitOps (don't choose one)" (already correct)

Line 404: Should be "Be pragmatic, not dogmatic" (already correct)

Line 418: Should be "Invest in observability (GitOps doesn't replace monitoring)" (already correct)

Actually, upon closer inspection, all H2 headings are correctly using sentence case. Well done!

Spelling/Grammar: Minor issues

Line 304: YouTube embed - verify video ID is correct: OhFdLTU5sAo

Content observations

Line 118: The note about API rate limits and polling intervals is excellent practical advice. The webhook recommendation is spot-on.

Line 151: Good clarification on the rendered manifests pattern vs. the anti-pattern of environment branches.

Line 219: Smart caveat about not rendering plaintext secrets in the rendered manifests pattern.

Line 271: Excellent warning about auto-remediation exclusion lists - this is a common production pitfall.

Line 377: The Statsig case study link should be verified for accuracy.

🔍 Verification Needed

I recommend verifying these external links are accessible:

• https://opengitops.dev/
• https://www.pulumi.com/kubecon/ (KubeCon Europe 2026 - future event)
• https://argoproj.github.io/cd/
• https://fluxcd.io/
• https://github.com/adrienverge/yamllint
• https://github.com/yannh/kubeconform
• https://www.openpolicyagent.org/
• https://www.conftest.dev/
• https://kyverno.io/
• https://argoproj.github.io/rollouts/
• https://flagger.app/
• https://kargo.io/
• https://external-secrets.io/
• https://sealed-secrets.netlify.app/
• https://github.com/getsops/sops
• https://github.com/gitops-bridge-dev/gitops-bridge
• https://www.statsig.com/blog/scaling-infra-with-pulumi-argocd
• https://prometheus.io/
• https://grafana.com/

📦 Image Assets

Two image files added:

• gitops-meme.png - Drake meme used at line 77
• meta.png - Social media preview image

Both images appear properly referenced. Verify both have appropriate alt text (the Drake meme does at line 77).

✨ Recommendation

Approve with minor fix: Add the trailing newline to line 445. This is a quick fix that can be addressed before merge.

The content is production-ready and provides genuine value to readers implementing GitOps. The writing quality is strong, the technical accuracy appears sound, and the real-world examples add significant credibility.

---

Mention @claude if you'd like me to review any specific sections in more detail or help with the trailing newline fix.

[pulumi-bot]

Your site preview for commit e936739 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-17468-e9367394.s3-website.us-west-2.amazonaws.com.