duocthu/docs-legacy/adr/0002-argocd-gitops.md

ADR 0002: Use the team's existing ArgoCD instance for deployment (GitOps)

Status

Accepted — still the target, not yet implemented. Not superseded by the current production setup.

Since 2026-08-10 the project has a different, interim deployment: a single EC2 box running infra/docker/docker-compose.prod.yml behind Caddy, deployed by .github/workflows/deploy.yml over SSH. That was built to get a working demo online, not to replace this decision. Migrating to the team's Kubernetes

• ArgoCD remains planned work, and the expensive prerequisite — containerising both apps — is already done, so the Dockerfiles and compose services port over.

Two things must still happen and neither has been started:

1. Repository move to the team's self-hosted Gitea (company domain), which is where the GitOps repo is meant to live. The project stays on private GitHub until that move is deliberately made. Note the hard boundary already in force: the team's existing git.vinmec.tech/ai-team/gitops repository is reference-only — never push this project into it.
2. Filling in the scaffolds this ADR assumes exist. infra/helm/medical-chatbot/templates/ and infra/k8s/** are empty (.gitkeep only), the chart is version 0.0.0, and every infra/argocd/applications/*/app.yaml still carries unresolved TODOs for project, repo URL and destination cluster.

Context

Phase 6 of the build roadmap needs a way to actually deploy the Helm chart to Kubernetes across dev/staging/prod. The original scaffold (infra/ci/github-actions/deploy-cd.yml) assumed a push-based CI deploy step (CI runs helm upgrade/kubectl apply directly against the cluster). The team already runs an ArgoCD instance used by other projects.

Decision

Deploy via GitOps through the team's existing ArgoCD instance instead of building a custom push-based CD pipeline. ArgoCD Applications (infra/argocd/applications/{dev,staging,prod}/app.yaml) point at infra/helm/medical-chatbot in this repo; ArgoCD watches the repo and reconciles the cluster to match.

Rationale

• Reuses infrastructure the team already operates and trusts, instead of standing up a parallel deploy mechanism.
• GitOps gives an auditable history of every deploy (it's just git commits changing values files/image tags) and a built-in rollback path (revert the commit).
• Removes the need for CI to hold cluster credentials — CI's job shrinks to "build, test, push image, bump tag," which is a smaller security surface than "CI can directly mutate the production cluster."
• Prod uses a non-automated syncPolicy (manual approval in ArgoCD) while dev/staging auto-sync, matching normal caution around production changes.

Consequences

• CI workflows (infra/ci/github-actions/*.yml) build/test/push images and bump the relevant values-<env>.yaml image tag + push that commit; they do not call kubectl/helm against any cluster directly.
• Actual deploy execution and health/sync status live in the team's ArgoCD UI/CLI, outside this repo — runbooks in docs/runbooks/ should document how to check sync status and roll back once the team's ArgoCD instance details (cluster/server, project, repo URL) are confirmed (see TODOs in infra/argocd/README.md).
• If the team's ArgoCD instance becomes unavailable or this project needs to fully own its own deploy tooling later, the push-based deploy-cd.yml approach remains a documented fallback.