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.