| name | gitops-workflows |
| description | GitOps deployment patterns with ArgoCD and Flux. Use when implementing Git-based infrastructure management, continuous deployment, or declarative operations. |
GitOps Workflows
Git as the single source of truth for declarative infrastructure and applications.
When to Use
- Implementing continuous deployment to Kubernetes
- Managing infrastructure changes through Git
- Setting up ArgoCD or Flux
- Designing promotion workflows (dev → staging → prod)
- Implementing drift detection and remediation
Core Principles
| Principle | Description |
|---|
| Declarative | Desired state described in Git |
| Versioned | Full history of changes |
| Automated | Changes applied automatically |
| Auditable | Git commits = audit trail |
Repository Structure
Monorepo Pattern
gitops-repo/
├── apps/
│ ├── base/ # Base manifests
│ │ └── myapp/
│ │ ├── deployment.yaml
│ │ ├── service.yaml
│ │ └── kustomization.yaml
│ └── overlays/
│ ├── development/
│ │ └── kustomization.yaml
│ ├── staging/
│ │ └── kustomization.yaml
│ └── production/
│ └── kustomization.yaml
│
├── infrastructure/
│ ├── base/
│ │ ├── cert-manager/
│ │ ├── ingress-nginx/
│ │ └── monitoring/
│ └── overlays/
│ └── production/
│
└── clusters/
├── development/
│ └── apps.yaml # ArgoCD Application
├── staging/
└── production/
ArgoCD
Installation
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
Application Definition
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: myapp
namespace: argocd
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
project: default
source:
repoURL: https://github.com/org/gitops-repo.git
targetRevision: main
path: apps/overlays/production
destination:
server: https://kubernetes.default.svc
namespace: myapp
syncPolicy:
automated:
prune: true
selfHeal: true
allowEmpty: false
syncOptions:
- CreateNamespace=true
- PrunePropagationPolicy=foreground
- PruneLast=true
retry:
limit: 5
backoff:
duration: 5s
factor: 2
maxDuration: 3m
ApplicationSet (Multi-Environment)
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: myapp
namespace: argocd
spec:
generators:
- list:
elements:
- cluster: development
url: https://dev-cluster.example.com
- cluster: staging
url: https://staging-cluster.example.com
- cluster: production
url: https://prod-cluster.example.com
template:
metadata:
name: 'myapp-{{cluster}}'
spec:
project: default
source:
repoURL: https://github.com/org/gitops-repo.git
targetRevision: main
path: 'apps/overlays/{{cluster}}'
destination:
server: '{{url}}'
namespace: myapp
syncPolicy:
automated:
prune: true
Flux
Installation
flux bootstrap github \
--owner=my-org \
--repository=gitops-repo \
--branch=main \
--path=clusters/production \
--personal
GitRepository Source
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
name: gitops-repo
namespace: flux-system
spec:
interval: 1m
url: https://github.com/org/gitops-repo
ref:
branch: main
secretRef:
name: github-token
Kustomization
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: myapp
namespace: flux-system
spec:
interval: 10m
targetNamespace: myapp
sourceRef:
kind: GitRepository
name: gitops-repo
path: ./apps/overlays/production
prune: true
healthChecks:
- apiVersion: apps/v1
kind: Deployment
name: myapp
namespace: myapp
timeout: 2m
HelmRelease
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: myapp
namespace: myapp
spec:
interval: 5m
chart:
spec:
chart: myapp
version: "1.x"
sourceRef:
kind: HelmRepository
name: myrepo
namespace: flux-system
values:
replicas: 3
image:
tag: v1.0.0
valuesFrom:
- kind: ConfigMap
name: myapp-values
Promotion Strategies
Environment Promotion
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Development │────▶│ Staging │────▶│ Production │
│ │ │ │ │ │
│ Auto-sync │ │ Auto-sync │ │ Manual/Gate │
│ on commit │ │ on merge │ │ approval │
└─────────────┘ └─────────────┘ └─────────────┘
Image Update Automation (Flux)
apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageRepository
metadata:
name: myapp
namespace: flux-system
spec:
image: registry.example.com/myapp
interval: 1m
---
apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImagePolicy
metadata:
name: myapp
namespace: flux-system
spec:
imageRepositoryRef:
name: myapp
policy:
semver:
range: 1.x
---
apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
name: myapp
namespace: flux-system
spec:
interval: 1m
sourceRef:
kind: GitRepository
name: gitops-repo
git:
checkout:
ref:
branch: main
Kustomize Overlays
Base Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
spec:
replicas: 1
selector:
matchLabels:
app: myapp
template:
metadata:
labels:
app: myapp
spec:
containers:
- name: myapp
image: myapp:latest
ports:
- containerPort: 8080
resources:
requests:
cpu: 100m
memory: 128Mi
Production Overlay
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: myapp-prod
resources:
- ../../base/myapp
replicas:
- name: myapp
count: 5
images:
- name: myapp
newTag: v1.2.3
patches:
- patch: |-
- op: replace
path: /spec/template/spec/containers/0/resources
value:
requests:
cpu: 500m
memory: 512Mi
limits:
cpu: 1000m
memory: 1Gi
target:
kind: Deployment
name: myapp
configMapGenerator:
- name: myapp-config
literals:
- LOG_LEVEL=info
- ENV=production
Best Practices
- Separate app and infra repos for different change velocities
- Use sealed-secrets or external-secrets for secrets in Git
- Implement branch protection on GitOps repos
- Use PR reviews for production changes
- Set up notifications for sync failures
- Implement rollback procedures via Git revert
Troubleshooting
argocd app list
argocd app get myapp
argocd app sync myapp
argocd app history myapp
argocd app rollback myapp <revision>
flux get all
flux reconcile kustomization myapp
flux logs --follow
flux events
Integration
Works with:
/k8s - Kubernetes manifests/terraform - Infrastructure provisioning/devops - CI/CD pipelinespolicy-as-code skill - Pre-commit validation
