playbooks

home / skills / nickcrew / claude-cortex / gitops-workflows

gitops-workflows skill

/skills/gitops-workflows

This skill helps you implement production-grade GitOps workflows with ArgoCD and Flux for declarative, multi-environment Kubernetes deployments.

npx playbooks add skill nickcrew/claude-cortex --skill gitops-workflows

Review the files below or copy the command above to add this skill to your agents.

Files (10)
SKILL.md
6.2 KB
---
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

Overview

This skill provides expert guidance for implementing production-grade GitOps workflows using ArgoCD and Flux for declarative Kubernetes deployments. It focuses on repository design, secure secret handling, sync and reconciliation policies, progressive delivery patterns, and reliable rollback and promotion strategies. Use it to standardize CI/CD for multi-environment or multi-cluster Kubernetes infrastructures.

How this skill works

The skill breaks GitOps adoption into concrete steps: choose repository structure, select an operator (ArgoCD or Flux), configure secret management, define sync and reconciliation policies, set up environment promotion, and implement progressive delivery and rollback procedures. It explains tool-specific capabilities (ApplicationSets, ImageUpdateAutomation, Rollouts) and maps them to common operational patterns and risk controls.

When to use it

  • Implementing GitOps principles for Kubernetes deployments
  • Automating continuous delivery from Git repositories
  • Managing multi-cluster or multi-environment deployments
  • Adopting progressive delivery (canary, blue-green) for risky changes
  • Designing secure secret workflows for Git-stored manifests

Best practices

  • Treat cluster state as declarative and versioned in Git with clear audit trails
  • Never commit unencrypted secrets; use Sealed Secrets, SOPS, or External Secrets
  • Automate non-prod sync with prune and self-heal; gate production with approvals
  • Design repository structure based on team boundaries and deployment independence
  • Add health checks and dependency ordering to avoid partial or broken rollouts

Example use cases

  • Set up ArgoCD App of Apps to manage platform-level and app-level manifests across clusters
  • Use Flux with ImageUpdateAutomation to automatically promote semver image updates to staging
  • Implement canary rollouts with Argo Rollouts or Flagger and a service mesh for traffic shifting
  • Create a Git-based promotion flow where CI tags an image and environment overlays pick it up
  • Configure External Secrets Operator to sync credentials from Vault or cloud KMS into clusters

FAQ

Which tool should I pick, ArgoCD or Flux?

Choose ArgoCD if you want a UI, strong RBAC and App-of-Apps patterns; choose Flux for a lighter, CLI-native approach with native image automation and deep Kustomize/Helm integration.

How should I handle secrets in GitOps?

Never store plaintext secrets. Use Sealed Secrets for client-side encryption, SOPS with KMS/age for file encryption, or External Secrets to sync from a managed secret store.