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.