GitOps CI Guru

Your specialized agent for building reliable GitOps-driven CI/CD pipelines, automating deployments, and ensuring every code change ships safely and predictably.

When to Use This Agent

Choose GitOps CI Guru when:

• Setting up or improving GitOps workflows with ArgoCD, Flux, or similar tools
• Building CI pipelines that validate, test, and deploy on every commit
• Debugging deployment failures, pipeline flakiness, or environment drift
• Implementing progressive delivery (canary, blue-green, feature flags)
• Designing multi-environment promotion strategies (dev → staging → production)

Consider alternatives when:

• You need infrastructure provisioning without CI/CD — use a Terraform agent
• You're focused on application architecture — use a cloud architect agent
• You need security-focused pipeline hardening — use a security engineer agent

Quick Start

Copy
# .claude/agents/gitops-ci.yml
name: GitOps CI Guru
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: GitOps and CI/CD specialist for pipeline automation, deployment strategies, and continuous delivery

Example invocation:

claude "Set up an ArgoCD Application that deploys from our Helm chart in the deploy/ directory with automated sync and self-healing enabled"

Core Concepts

GitOps Principles

Principle	Implementation	Tooling
Declarative	All config in Git (YAML, HCL, Helm)	Kustomize, Helm, Terraform
Versioned	Git as single source of truth	GitHub, GitLab, Bitbucket
Automated	Changes applied automatically on merge	ArgoCD, Flux, Jenkins X
Continuously Reconciled	Drift detection and self-healing	ArgoCD sync, Flux reconciliation

CI/CD Pipeline Structure

Copy
# Typical GitOps pipeline stages
pipeline:
  - lint:        # Code quality, YAML validation
  - test:        # Unit, integration, contract tests
  - build:       # Container image, artifact creation
  - scan:        # Security scanning, vulnerability checks
  - push:        # Registry push, manifest update
  - deploy-dev:  # Auto-deploy to dev environment
  - promote:     # Manual/automated promotion gate
  - deploy-prod: # Production deployment via GitOps
  - verify:      # Smoke tests, health checks

Configuration

Parameter	Description	Default
gitops_tool	GitOps controller (argocd, flux, custom)	argocd
ci_platform	CI system (github-actions, gitlab-ci, jenkins)	github-actions
deploy_strategy	Deployment strategy (rolling, canary, blue-green)	rolling
environments	Environment promotion chain	dev,staging,prod
auto_sync	Enable auto-sync on merge to main	true

Best Practices

1. Make deployments boring through automation. The goal is zero-touch deployments where merging to main triggers a fully automated, validated release. If deployments need human intervention, you haven't automated enough of the validation and rollback logic.

2. Keep environment configs DRY with overlays. Use Kustomize overlays or Helm value files to manage per-environment differences. The base configuration should be identical across environments — only connection strings, replica counts, and feature flags should vary.

3. Implement deployment verification gates. After every deployment, run automated smoke tests and health checks before marking the release as successful. ArgoCD health checks and Flux post-deployment hooks are built for this.

4. Version your container images with immutable tags. Never deploy latest. Use Git SHA or semantic version tags so every deployment is reproducible and rollbacks are instant. Tag immutability prevents silent image overwrites.

5. Separate application repos from GitOps config repos. Application code and deployment manifests should live in different repositories. This keeps CI pipelines focused, allows different access controls, and prevents accidental production changes from application PRs.

Common Issues

ArgoCD shows OutOfSync but nothing has changed. This often happens with Helm hooks, auto-generated fields (like metadata.generation), or resources modified by admission controllers. Add the drifting fields to spec.ignoreDifferences in your ArgoCD Application resource, or use server-side diff to reduce false positives.

Pipeline fails intermittently on the same code. Flaky pipelines usually stem from test timing issues, network-dependent steps (pulling images, fetching dependencies), or shared state between jobs. Pin dependency versions, cache aggressively, isolate test environments, and add retry logic only for genuinely transient failures like registry timeouts.

Environment drift between staging and production. Drift happens when changes are applied directly to production (kubectl apply, console edits) instead of through Git. Enable ArgoCD self-healing to auto-revert manual changes, set up drift detection alerts, and enforce RBAC that prevents direct cluster modifications.