gitopsUse this skill when the user says 'GitOps', 'ArgoCD', 'Flux', 'Git as source of truth', 'sync policy', 'drift detection', 'multi-env GitOps', 'Application CRD', 'Kustomize', 'Helm with GitOps', 'sync waves', 'phased rollouts'. Covers: declarative deployments, ArgoCD setup, Flux setup, sync strategies, drift detection, multi-environment promotion, secrets in…
Independent GitHub snapshot · Automated classification · Original documentation governs
Manage Kubernetes deployments using Git as the single source of truth with ArgoCD or Flux. Covers repository structure, application definitions, sync policies, environment promotion, drift detection, and secret management.
Git (desired state) -> GitOps Controller watches repo
-> Compares with cluster state
-> Detects drift (manual change or config divergence)
-> Applies desired state to cluster
-> Reports sync status
-> Loops continuously (default every 3-5 minutes)
Pull-based (GitOps native): Agent in cluster pulls from Git. Cluster initiates all changes. No external access to cluster API needed. More secure.
Push-based (CI/CD traditional): CI system pushes to cluster. Cluster API exposed to CI system. Higher blast radius (CI compromise = cluster compromise).
Recommendation: Always use pull-based for production.
Exact user phrases: "GitOps", "ArgoCD", "Flux", "Git as source of truth", "sync policy", "drift detection", "Application CRD", "sync waves".
Application CRDs, Flux Kustomization/HelmRelease YAMLs, sync policies, directory structure.
YAML manifests with no extraneous explanation.
No preamble. No postamble. No explanations.
| Feature | ArgoCD | Flux |
|---|---|---|
| Reconciliation | Every 3 min (default) | Configurable interval |
| UI | Rich web UI, SSO | CLI-only (no GUI) |
| Sync Waves | Annotations | depends-on |
| Rollback | One-click via UI | git revert |
| Multi-cluster | ApplicationSet CRD | Kustomization per cluster |
| Secret encryption | SOPS plugin | SOPS native |
| Blue/green, canary | AnalysisTemplate + Argo Rollouts | None (requires Flagger) |
| SSO | Built-in (OIDC, Dex, GitHub, GitLab) | Dex/External |
| RBAC | Project-level, fine-grained | K8s RBAC |
| Weight | Medium (CRD-heavy) | Lightweight |
| Community | Large, CNCF graduated | Large, CNCF graduated |
| Learning curve | Moderate | Lower |
| Method | Description | Best For |
|---|---|---|
| Branch per env | dev branch = dev cluster, main = prod | Simple, clear separation |
| Path per env | Single branch, overlays/dev = dev cluster | Kustomize native |
| Tag-based | Git tag triggers promotion to next env | Release engineering |
| PR-based | PR merges promote between environments | Review-driven |
infra-repo/
base/
kustomization.yaml
deployment.yaml
service.yaml
ingress.yaml
configmap.yaml
overlays/
dev/
kustomization.yaml
deployment-patch.yaml
configmap-dev.yaml
staging/
kustomization.yaml
deployment-patch.yaml
configmap-staging.yaml
prod/
kustomization.yaml
deployment-patch.yaml
configmap-prod.yaml
hpa.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app-dev
namespace: argocd
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
project: default
source:
repoURL: https://github.com/org/infra.git
targetRevision: main
path: overlays/dev
destination:
server: https://kubernetes.default.svc
namespace: my-app-dev
syncPolicy:
automated:
prune: true
selfHeal: true
allowEmpty: false
syncOptions:
- CreateNamespace=true
- PruneLast=true
- ApplyOutOfSyncOnly=true
- RespectIgnoreDifferences=true
- ServerSideApply=true
retry:
limit: 5
backoff:
duration: 5s
factor: 2
maxDuration: 3m
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers:
- /spec/replicas
- group: autoscaling
kind: HorizontalPodAutoscaler
jsonPointers:
- /spec/metrics
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
name: my-app
namespace: flux-system
spec:
interval: 1m
url: https://github.com/org/infra.git
ref:
branch: main
ignore: |
.github/
.gitignore
*.md
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: my-app-dev
namespace: flux-system
spec:
interval: 5m
path: ./overlays/dev
prune: true
sourceRef:
kind: GitRepository
name: my-app
wait: true
timeout: 5m
healthChecks:
- apiVersion: apps/v1
kind: Deployment
name: my-app
namespace: my-app-dev
postBuild:
substitute:
env: dev
image_tag: latest
substituteFrom:
- kind: ConfigMap
name: cluster-vars
dependsOn:
- name: infrastructure
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: my-app-prod
namespace: flux-system
spec:
interval: 5m
path: ./overlays/prod
prune: true
sourceRef:
kind: GitRepository
name: my-app
dependsOn:
- name: my-app-dev
decryption:
provider: sops
secretRef:
name: sops-gpg
apiVersion: v1
kind: Namespace
metadata:
name: my-app
annotations:
argocd.argoproj.io/sync-wave: "-5"
---
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
namespace: my-app
annotations:
argocd.argoproj.io/sync-wave: "-3"
---
apiVersion: v1
kind: Secret
metadata:
name: app-secrets
namespace: my-app
annotations:
argocd.argoproj.io/sync-wave: "-2"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
namespace: my-app
annotations:
argocd.argoproj.io/sync-wave: "0"
---
apiVersion: v1
kind: Service
metadata:
name: my-app
namespace: my-app
annotations:
argocd.argoproj.io/sync-wave: "1"
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
name: aws-secrets-manager
namespace: my-app
spec:
provider:
aws:
service: SecretsManager
region: us-east-1
auth:
jwt:
serviceAccountRef:
name: my-app-sa
---
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
name: app-secrets
namespace: my-app
spec:
refreshInterval: 1h
secretStoreRef:
name: aws-secrets-manager
kind: SecretStore
target:
name: app-secrets
creationPolicy: Owner
data:
- secretKey: DB_PASSWORD
remoteRef:
key: /prod/my-app/db-password
- secretKey: API_KEY
remoteRef:
key: /prod/my-app/api-key
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: my-app
namespace: argocd
spec:
generators:
- clusters:
selector:
matchLabels:
environment: dev
template:
metadata:
name: 'my-app-{{name}}'
spec:
project: default
source:
repoURL: https://github.com/org/infra.git
targetRevision: main
path: 'overlays/{{metadata.labels.environment}}'
destination:
server: '{{server}}'
namespace: 'my-app-{{metadata.labels.environment}}'
syncPolicy:
automated:
prune: true
selfHeal: true
# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: my-app-prod
bases:
- ../../base
patchesStrategicMerge:
- deployment-patch.yaml
- hpa.yaml
configMapGenerator:
- name: app-config
behavior: merge
literals:
- NODE_ENV=production
- LOG_LEVEL=info
- API_URL=https://api.example.com
images:
- name: my-app
newTag: v1.2.3
replicas:
- name: my-app
count: 5
commonLabels:
environment: production
team: backend
Someone runs kubectl edit and changes drift. Self-heal reverts it without warning, confusing the team. Always change in Git. Educate team that Git is the single source of truth.
Anyone with repo access sees production secrets. Secrets in Git are visible in commit history forever. Use SealedSecrets, External Secrets Operator, or SOPS.
Resources removed from Git stay in the cluster because prune is disabled. Orphaned resources accumulate and drift grows. Enable prune on all sync policies.
Self-heal silently reverts manual changes without notifying anyone. Monitor sync status and alert on out-of-sync states. Document self-heal behavior in team runbook.
Too many Kustomize layers make changes error-prone and hard to reason about. Keep base simple. Use overlays per environment. Avoid deep nesting.
Deployments start before ConfigMaps exist, causing application startup failures. Use sync-wave annotations (ArgoCD) or depends-on (Flux) for resource ordering.
Self-heal silently reverts changes without notification, masking operational issues. Monitor sync status and alert on OutOfSync state or SyncFailed.
No traceability of what version is deployed. Rollback is impossible. Pin to specific branch, tag, or commit hash. Use semantic versioning for releases.
ArgoCD: reconciliation, drift detection, UI, sync waves, SSO, heavyweight. Flux: reconciliation, lightweight, SOPS native, depends-on, lighter. Helm-only: no reconciliation or drift detection, good for simple deployments. kubectl apply: manual, no reconciliation, not recommended for production.
GitOps (pull-based): agent in cluster pulls desired state from Git. No cluster API exposed to CI. Lower blast radius. Traditional (push-based): CI pushes directly to cluster. Cluster API must be accessible from CI. Higher risk if CI is compromised.
After completing this skill:
| Decision | Push-based (CI/CD pushes) | Pull-based (ArgoCD/Flux) |
|---|---|---|
| Trigger | CI pipeline completion | Git repo change (commit) |
| Drift detection | Manual or CI-scheduled | Continuous reconciliation |
| Network model | CI → Cluster API | Cluster pulls from Git |
| Secret handling | CI secrets injected | Sealed secrets, SOPS, ESO |
| RBAC | CI service account | Cluster-local controller |
| Best for | Simple, single-env | Multi-env, compliance-heavy |
| Aspect | Single Repo | Per-Environment Repos |
|---|---|---|
| Atomicity | One commit for all envs | Multiple commits/PRs |
| Promotion | Branch/tag promotion | Cross-repo promotion |
| Auditing | Per-path | Per-repo |
| Complexity | Simple | Higher (sync between repos) |
| Access control | Same access to all envs | Isolated per environment |
| Rollback | Revert commit | Revert per-env commit |
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: production-app
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/acme/config.git
targetRevision: main
path: overlays/production
destination:
server: https://kubernetes.default.svc
namespace: production
syncPolicy:
automated:
prune: true
selfHeal: true
allowEmpty: false
syncOptions:
- CreateNamespace=true
- PruneLast=true
- ApplyOutOfSyncOnly=true
retry:
limit: 5
backoff:
duration: 5s
factor: 2
maxDuration: 3m
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: app-config
namespace: flux-system
spec:
interval: 5m
path: ./overlays/production
prune: true
sourceRef:
kind: GitRepository
name: config-repo
healthChecks:
- apiVersion: apps/v1
kind: Deployment
name: app
namespace: production
postBuild:
substitute:
environment: production
region: us-east-1
substituteFrom:
- kind: ConfigMap
name: cluster-vars
dependsOn:
- name: cluster-infra
#!/usr/bin/env bash
promote_overlay() {
local from_env=$1
local to_env=$2
git checkout -b "promote-$to_env-$(date +%s)"
# Copy overlay config from source to target environment
rsync -av "overlays/$from_env/" "overlays/$to_env/"
find "overlays/$to_env/" -name "kustomization.yaml" -exec \
sed -i "s/namespace: $from_env/namespace: $to_env/g" {} \;
git add overlays/
git commit -m "promote: $from_env → $to_env"
git push origin HEAD
# Create PR with labels
gh pr create \
--base main \
--title "Promote $from_env → $to_env" \
--label gitops,promotion \
--body "Promoting configurations from $from_env to $to_env"
}
ignoreDifferences — masks real configuration drift and hides problemssourceNamespaces to prevent cross-team resource access