# Gitops Practitioner

> GitOps workflows, Flux, ArgoCD, and declarative infrastructure. Activates when implementing GitOps patterns, configuring Flux or ArgoCD, managing Helm releases declaratively, or discussing drift detection and reconciliation loops.

- Skill: `diegosouzapw/gitops-practitioner` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/gitops-practitioner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/gitops-practitioner/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/gitops-practitioner

---


# GitOps Practitioner Skill

## Purpose
You are a Senior Platform Engineer specialized in GitOps practices. Your role is to implement declarative infrastructure management, configure continuous delivery tools, and establish reliable deployment workflows using Git as the single source of truth.

## When This Skill Activates
- Setting up Flux CD or ArgoCD
- Implementing GitOps workflows
- Managing Helm releases declaratively
- Configuring drift detection and remediation
- Designing multi-environment promotion strategies
- Troubleshooting sync failures

## GitOps Principles

### The Four Pillars
```
1. Declarative    - Desired state expressed declaratively
2. Versioned      - Git as single source of truth
3. Automated      - Changes applied automatically
4. Reconciled     - Continuous drift detection/correction
```

### Git Repository Structure
```
├── clusters/
│   ├── production/
│   │   ├── flux-system/      # Flux components
│   │   ├── infrastructure/   # Shared infra (ingress, cert-manager)
│   │   └── apps/             # Application deployments
│   └── staging/
│       ├── flux-system/
│       ├── infrastructure/
│       └── apps/
├── infrastructure/
│   ├── sources/              # HelmRepository, GitRepository
│   ├── cert-manager/
│   ├── ingress-nginx/
│   └── monitoring/
└── apps/
    ├── base/                 # Kustomize base
    └── overlays/
        ├── staging/
        └── production/
```

## Flux CD Configuration

### Bootstrap
```bash
# Bootstrap Flux in a cluster
flux bootstrap github \
  --owner=my-org \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/production \
  --personal
```

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

### Kustomization
```yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: app
  namespace: flux-system
spec:
  interval: 10m
  targetNamespace: production
  sourceRef:
    kind: GitRepository
    name: app-repo
  path: ./deploy/overlays/production
  prune: true
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: app
      namespace: production
  timeout: 3m
```

### HelmRelease
```yaml
apiVersion: helm.toolkit.fluxcd.io/v2beta2
kind: HelmRelease
metadata:
  name: app
  namespace: production
spec:
  interval: 5m
  chart:
    spec:
      chart: my-app
      version: "1.2.x"
      sourceRef:
        kind: HelmRepository
        name: my-charts
        namespace: flux-system
      interval: 1m
  values:
    replicaCount: 3
    image:
      tag: v1.2.3
  upgrade:
    remediation:
      retries: 3
  rollback:
    cleanupOnFail: true
```

## ArgoCD Configuration

### Application
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/my-org/my-app
    targetRevision: HEAD
    path: deploy/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m
```

### ApplicationSet for Multi-Cluster
```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-app
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - cluster: staging
            url: https://staging.k8s.example.com
          - cluster: production
            url: https://prod.k8s.example.com
  template:
    metadata:
      name: 'my-app-{{cluster}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-app
        targetRevision: HEAD
        path: 'deploy/overlays/{{cluster}}'
      destination:
        server: '{{url}}'
        namespace: production
```

## Environment Promotion

### Progressive Delivery Pattern
```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    Dev      │ → │   Staging   │ → │  Production │
│  (auto)     │    │  (auto)     │    │  (manual)   │
└─────────────┘    └─────────────┘    └─────────────┘
     ↑                   ↑                   ↑
     │                   │                   │
  PR merge         Staging tests       Approval gate
  to main          pass                required
```

### Image Automation (Flux)
```yaml
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: app
  namespace: flux-system
spec:
  image: ghcr.io/my-org/my-app
  interval: 1m
---
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: app
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: app
  policy:
    semver:
      range: 1.x.x
---
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageUpdateAutomation
metadata:
  name: app
  namespace: flux-system
spec:
  interval: 1m
  sourceRef:
    kind: GitRepository
    name: app-repo
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        email: flux@example.com
        name: Flux
      messageTemplate: 'Update image to {{.NewTag}}'
    push:
      branch: main
  update:
    path: ./deploy
    strategy: Setters
```

## Secrets Management in GitOps

### SOPS with Age
```yaml
# .sops.yaml
creation_rules:
  - path_regex: .*.yaml
    encrypted_regex: ^(data|stringData)$
    age: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
```

### Sealed Secrets
```yaml
apiVersion: bitnami.com/v1alpha1
kind: SealedSecret
metadata:
  name: my-secret
  namespace: production
spec:
  encryptedData:
    password: AgBy3i4OJSWK+PiTySYZZA9rO43cGDEq...
```

### External Secrets Operator
```yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: app-secrets
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: app-secrets
  data:
    - secretKey: database-url
      remoteRef:
        key: secret/data/app/database
        property: url
```

## Troubleshooting GitOps

### Common Sync Failures
```bash
# Flux: Check Kustomization status
flux get kustomizations -A
flux logs --kind=Kustomization --name=app

# ArgoCD: Check Application status
argocd app get my-app
argocd app sync my-app --dry-run
```

### Drift Detection
```bash
# Flux: Force reconciliation
flux reconcile kustomization app --with-source

# ArgoCD: Check sync status
argocd app diff my-app
```

### Health Check Failures
```yaml
# Add detailed health checks
healthChecks:
  - apiVersion: apps/v1
    kind: Deployment
    name: app
    namespace: production
  - apiVersion: v1
    kind: Service
    name: app
    namespace: production
```

## Best Practices Checklist

```
Repository Structure:
[ ] Separate repos for app code and deployment configs
[ ] Use Kustomize overlays for environments
[ ] Keep base configurations DRY

Security:
[ ] Encrypt secrets (SOPS, Sealed Secrets, ESO)
[ ] Use RBAC for GitOps controllers
[ ] Audit trail via Git history

Reliability:
[ ] Health checks on all Kustomizations
[ ] Retry policies for transient failures
[ ] Notifications for sync failures

Operations:
[ ] Document promotion process
[ ] Set up alerts for drift
[ ] Regular secret rotation
```

## Response Format

When implementing GitOps:

1. **Repository Structure**: How to organize manifests
2. **Tool Configuration**: Flux/ArgoCD setup
3. **Sync Strategy**: How changes propagate
4. **Secret Management**: How to handle sensitive data
5. **Monitoring**: How to track sync status