Gitops Workflow

When to use this skill

Use Gitops Workflow when an AI agent needs a reusable SKILL.md workflow for this job: Implement GitOps workflows with ArgoCD and Flux for automated, declarative Kubernetes deployments with continuous reconciliation. Use when implementing GitOps practices, automating Kubernetes deployments, or setting up declarative infrastructure management.

When not to use it

Skip Gitops Workflow when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

1. Personal install: create ~/.claude/skills/gitops-workflow/SKILL.md (and any bundled scripts) so Claude Code, Claude Desktop, and compatible agents can load it in every project.
2. Project install: commit the same folder at .claude/skills/gitops-workflow/ so teammates get the skill with the repo.
3. Restart the agent session after copying files so it re-scans the skills directory, then ask for the task in words that match the skill description.

Full install guide for Claude, Cursor, and Codex

What this skill does

# GitOps Workflow

Complete guide to implementing GitOps workflows with ArgoCD and Flux for automated Kubernetes deployments.

## Purpose

Implement declarative, Git-based continuous delivery for Kubernetes using ArgoCD or Flux CD, following OpenGitOps principles.

## When to Use This Skill

- Set up GitOps for Kubernetes clusters - Automate application deployments from Git - Implement progressive delivery strategies - Manage multi-cluster deployments - Configure automated sync policies - Set up secret management in GitOps

## OpenGitOps Principles

1. **Declarative** - Entire system described declaratively 2. **Versioned and Immutable** - Desired state stored in Git 3. **Pulled Automatically** - Software agents pull desired state 4. **Continuously Reconciled** - Agents reconcile actual vs desired state

## ArgoCD Setup

### 1. Installation

```bash # Create namespace kubectl create namespace argocd

# Install ArgoCD kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Get admin password kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d ```

**Reference:** See `references/argocd-setup.md` for detailed setup

### 2. Repository Structure

``` gitops-repo/ ├── apps/ │ ├── production/ │ │ ├── app1/ │ │ │ ├── kustomization.yaml │ │ │ └── deployment.yaml │ │ └── app2/ │ └── staging/ ├── infrastructure/ │ ├── ingress-nginx/ │ ├── cert-manager/ │ └── monitoring/ └── argocd/ ├── applications/ └── projects/ ```

### 3. Create Application

```yaml # argocd/applications/my-app.yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app namespace: argocd spec: project: default source: repoURL: https://github.com/org/gitops-repo targetRevision: main path: apps/production/my-app destination: server: https://kubernetes.default.svc namespace: production syncPolicy: automated: prune: true selfHeal: true syncOptions: - CreateNamespace=true ```

### 4. App of Apps Pattern

```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: applications namespace: argocd spec: project: default source: repoURL: https://github.com/org/gitops-repo targetRevision: main path: argocd/applications destination: server: https://kubernetes.default.svc namespace: argocd syncPolicy: automated: {} ```

## Flux CD Setup

### 1. Installation

```bash # Install Flux CLI curl -s https://fluxcd.io/install.sh | sudo bash

# Bootstrap Flux flux bootstrap github \ --owner=org \ --repository=gitops-repo \ --branch=main \ --path=clusters/production \ --personal ```

### 2. Create GitRepository

```yaml apiVersion: source.toolkit.fluxcd.io/v1 kind: GitRepository metadata: name: my-app namespace: flux-system spec: interval: 1m url: https://github.com/org/my-app ref: branch: main ```

### 3. Create Kustomization

```yaml apiVersion: kustomize.toolkit.fluxcd.io/v1 kind: Kustomization metadata: name: my-app namespace: flux-system spec: interval: 5m path: ./deploy prune: true sourceRef: kind: GitRepository name: my-app ```

## Sync Policies

### Auto-Sync Configuration

**ArgoCD:**

```yaml syncPolicy: automated: prune: true # Delete resources not in Git selfHeal: true # Reconcile manual changes allowEmpty: false retry: limit: 5 backoff: duration: 5s factor: 2 maxDuration: 3m ```

**Flux:**

```yaml spec: interval: 1m prune: true wait: true timeout: 5m ```

**Reference:** See `references/sync-policies.md`

## Progressive Delivery

### Canary Deployment with ArgoCD Rollouts

```yaml apiVersion: argoproj.io/v1alpha1 kind: Rollout metadata: name: my-app spec: replicas: 5 strategy: canary: steps: - setWeight: 20 - pause: { duration: 1m } - setWeight: 50 - pause: { duration: 2m } - setWeight: 100 ```

### Blue-Green Deployment

```yaml strategy: blueGreen: activeService: my-app previewService: my-app-preview autoPromotionEnabled: false ```

## Secret Management

### External Secrets Operator

```yaml apiVersion: external-secrets.io/v1beta1 kind: ExternalSecret metadata: name: db-credentials spec: refreshInterval: 1h secretStoreRef: name: aws-secrets-manager kind: SecretStore target: name: db-credentials data: - secretKey: password remoteRef: key: prod/db/password ```

### Sealed Secrets

```bash # Encrypt secret kubeseal --format yaml < secret.yaml > sealed-secret.yaml

# Commit sealed-secret.yaml to Git ```

## Best Practices

1. **Use separate repos or branches** for different environments 2. **Implement RBAC** for Git repositories 3. **Enable notifications** for sync failures 4. **Use health checks** for custom resources 5. **Implement approval gates** for production 6. **Keep secrets out of Git** (use External Secrets) 7. **Use App of Apps pattern** for organization 8. **Tag releases** for easy rollback 9. **Monitor sync status** with alerts 10. **Test changes** in staging first

## Troubleshooting

**Sync failures:**

```bash argocd app get my-app argocd app sync my-app --prune ```

**Out of sync status:**

```bash argocd app diff my-app argocd app sync my-app --force ```

## Related Skills

- `k8s-manifest-generator` - For creating manifests - `helm-chart-scaffolding` - For packaging applications

Intended uses

• Set up GitOps for Kubernetes clusters
• Automate application deployments from Git
• Implement progressive delivery strategies
• Manage multi-cluster deployments
• Configure automated sync policies
• Set up secret management in GitOps