GitOps
Overview
Use GitOps-first changes for infra and deployment workflows, then validate locally and let Argo CD reconcile. Only apply directly to the cluster when explicitly instructed or in an emergency.
Workflow
- Locate the source of truth
- Argo CD apps and overlays: argocd/ - Kubernetes manifests: kubernetes/ - IaC: tofu/, ansible/ - Service-specific instructions: nearest README.md
- Edit manifests in Git
- Prefer updating Argo CD apps/overlays instead of raw kubectl applies. - Keep environment-specific changes in overlays.
- Validate locally
- Argo lint: scripts/argo-lint.sh - Kubeconform: scripts/kubeconform.sh argocd - Terraform/tofu: bun run tf:plan (apply only when asked) - Ansible: bun run ansible
- Rollout discipline
- Note rollout/impact for changes in
argocd/,kubernetes/,tofu/,ansible/. - For Helm charts with kustomize, use:
mise exec helm@3 -- kustomize build --enable-helm <path>.
- Cluster access (exception-only)
- Use direct
kubectl applyonly when explicitly asked or in emergencies. - Always set namespace:
kubectl... -n <ns>.
- Deploy completion guardrail
- Only call a deploy "completed" after the Argo CD application is synced and healthy.
Pointers
- Use
references/gitops-checklist.mdfor quick commands and repo-specific notes.