Agent-Skills.md

Agent Skills: GitOps Workflows

GitOps workflows and patterns using ArgoCD and Flux for declarative Kubernetes deployments. Use when implementing CI/CD for Kubernetes, managing multi-environment deployments, or adopting declarative infrastructure practices.

UncategorizedID: NickCrew/claude-ctx-plugin/gitops-workflows

Repository

NickCrew/claude-ctx-plugin
NickCrewLicense: MIT
52

Skill Files

Browse the full folder contents for gitops-workflows.

Download Skill

Loading file tree…

skills/gitops-workflows/SKILL.md

Skill Metadata

Name
gitops-workflows
Description
GitOps workflows and patterns using ArgoCD and Flux for declarative Kubernetes deployments. Use when implementing CI/CD for Kubernetes, managing multi-environment deployments, or adopting declarative infrastructure practices.

GitOps Workflows

Expert guidance for implementing production-grade GitOps workflows using ArgoCD and Flux CD, covering declarative deployment patterns, progressive delivery strategies, multi-environment management, and secure secret handling for Kubernetes infrastructure.

When to Use This Skill

  • Implementing GitOps principles for Kubernetes deployments
  • Automating continuous delivery from Git repositories
  • Managing multi-cluster or multi-environment deployments
  • Implementing progressive delivery (canary, blue-green) strategies
  • Configuring automated sync policies and reconciliation
  • Managing secrets securely in GitOps workflows
  • Setting up environment promotion workflows
  • Designing repository structures for GitOps (monorepo vs multi-repo)
  • Implementing rollback strategies and disaster recovery
  • Establishing compliance and audit trails through Git

Core Concepts

The Four Principles

  1. Declarative: Entire system state expressed in code
  2. Versioned: Canonical state stored in Git with full history
  3. Pulled Automatically: Agents pull desired state (no push to prod)
  4. Continuously Reconciled: Automatic drift detection and correction

Key Benefits

  • Complete deployment history and audit trail
  • Fast rollback via Git operations
  • Enhanced security (no cluster credentials in CI)
  • Self-healing infrastructure
  • Multi-cluster consistency
  • Familiar Git workflows for infrastructure changes

Quick Reference

| Task | Load reference | | --- | --- | | GitOps principles and benefits | skills/gitops-workflows/references/core-principles.md | | Repository structure patterns (monorepo, multi-repo, branches) | skills/gitops-workflows/references/repository-structures.md | | ArgoCD setup, Applications, ApplicationSets | skills/gitops-workflows/references/argocd-implementation.md | | Flux bootstrap, sources, Kustomizations, HelmReleases | skills/gitops-workflows/references/flux-implementation.md | | Environment promotion strategies | skills/gitops-workflows/references/environment-promotion.md | | Secret management (Sealed Secrets, ESO, SOPS) | skills/gitops-workflows/references/secret-management.md | | Progressive delivery (canary, blue-green) | skills/gitops-workflows/references/progressive-delivery.md | | Rollback strategies and disaster recovery | skills/gitops-workflows/references/rollback-strategies.md | | Best practices and patterns | skills/gitops-workflows/references/best-practices.md |

Workflow Steps

1. Choose Repository Structure

Decision factors:

  • Team size and organization structure
  • Application coupling and dependencies
  • Access control requirements
  • Deployment frequency and independence

Options:

  • Monorepo: Single repo, unified platform teams, shared infrastructure
  • Multi-repo: Separate repos per app/team, independent release cycles
  • Environment branches: Git flow style, simple mental model

2. Select GitOps Tool

ArgoCD:

  • UI-focused with visual application management
  • App of Apps pattern for hierarchical deployments
  • ApplicationSets for multi-cluster deployments
  • Strong RBAC and project isolation

Flux:

  • CLI-first, GitOps Toolkit architecture
  • Native Kustomize and Helm support
  • Automated image updates
  • Lighter weight, cloud-native

3. Configure Secret Management

Never commit unencrypted secrets to Git

Options:

  • Sealed Secrets: Client-side encryption, simple workflow
  • External Secrets Operator: Sync from external secret stores (AWS, Vault, GCP)
  • SOPS: File-based encryption with age or cloud KMS

4. Implement Sync Policies

Non-production environments:

  • Automated sync with prune and selfHeal
  • Frequent reconciliation (1-5 minutes)
  • Fail fast with immediate feedback

Production environments:

  • Manual approval or gated automation
  • Health checks and wait conditions
  • Progressive delivery for high-risk changes
  • Sync windows for maintenance periods

5. Set Up Environment Promotion

Promotion strategies:

  • Git-based: Tag or branch promotion with Git operations
  • Kustomize overlays: Update image tags in environment-specific overlays
  • Automated updates: Flux ImageUpdateAutomation for semver policies

6. Configure Progressive Delivery

For high-risk changes:

  • ArgoCD Rollouts: Canary deployments with automated analysis
  • Flagger: Progressive delivery with metric-based promotion
  • Traffic shifting with Istio or other service mesh
  • Automated rollback on failed analysis

7. Establish Rollback Procedures

Git rollback:

  • git revert for specific commits
  • Tag-based rollback by updating targetRevision
  • Fast and declarative

Tool-specific:

  • ArgoCD: argocd app rollback with revision history
  • Flux: Suspend automation, manual rollback, resume

Common Mistakes

  1. Committing unencrypted secrets - Always use secret management solution
  2. No automated sync in non-prod - Slows development feedback
  3. Automated sync in production without gates - High risk of breaking changes
  4. Ignoring drift detection - Manual changes should be reconciled or alerted
  5. No health checks - Sync succeeds but app is unhealthy
  6. Missing dependency ordering - Apps deploy before infrastructure ready
  7. No rollback testing - Discover issues during actual incidents
  8. Inconsistent environments - Staging differs too much from production
  9. No promotion testing - Manual errors during environment promotion
  10. Weak RBAC - Too many permissions for GitOps service accounts

Resources

  • OpenGitOps: https://opengitops.dev/
  • ArgoCD Documentation: https://argo-cd.readthedocs.io/
  • Flux Documentation: https://fluxcd.io/docs/
  • ArgoCD Rollouts: https://argoproj.github.io/argo-rollouts/
  • Flagger: https://docs.flagger.app/
  • External Secrets Operator: https://external-secrets.io/
  • Sealed Secrets: https://github.com/bitnami-labs/sealed-secrets
  • SOPS: https://github.com/mozilla/sops