How dag-andersen/argocd-diff-preview works
Project type and purpose
• This is an open-source CLI tool (written in Go) packaged as a Docker image.
• Purpose: spin up an ephemeral Kubernetes cluster, install Argo CD, render manifests from two Git branches (base vs. target), compute a diff, and output it (e.g., as Markdown).
• It integrates with GitHub Actions (or any CI) to comment diffs on PRs, much like Terraform’s Atlantis.
File structure
• Top-level:
• cmd/ → CLI entry point (main.go, options.go)
• pkg/ → core libraries broken out by concern (argocd, k8s, diff, git, cluster provisioning, utils)
• Dockerfile → packages CLI into a container that mounts Docker socket and host folders
• argocd-config/ → Argo CD Helm values for overriding defaults
• examples/, docs/ → usage demos, tutorials, and a MkDocs-driven site
• .github/workflows/ → GitHub Actions pipelines (generate-diff, release Docker/binary, MkDocs)
• tests/ → integration test fixtures and Kind/Minikube configs
• Patterns:
• Modular Go packages (single responsibility in pkg/)
• CLI-on-Docker pattern (containerized tooling)
• Ephemeral-infrastructure provisioning (k3d/kind/minikube)
• GitOps flow via Argo CD in a throwaway cluster
README for additional insights
• Supported features: private repos, Helm charts, Kustomize overlays, multi-source Applications.
• CI integration: mounts base/target branches and Docker socket, sets env vars (TARGET_BRANCH, REPO), runs container.
a. Main components
1. Developer/CI trigger
2. Docker container (argocd-diff-preview image)
3. Docker daemon (host socket)
4. Ephemeral Kubernetes cluster (Kind/K3d/Minikube)
5. Argo CD control plane inside cluster
6. Git repositories (base-branch, target-branch)
7. Manifest extraction & diff engine (Go modules in pkg/)
8. Output sink (volume mount → output/diff.md)
9. GitHub API (optional: posting PR comment)
b. Relationships & interactions
• CI or user invokes the Docker container.
• Container talks to host Docker daemon (via mounted socket) to provision a cluster.
• Once cluster is up, container deploys Argo CD using Helm values from argocd-config/.
• Container points Argo CD at base and target branches as two Applications (or ApplicationSets).
• Argo CD syncs and renders manifests into the cluster’s discardable namespace.
• Container’s Go code calls into pkg/argoapplication and pkg/k8s to fetch live manifests from Argo CD.
• pkg/diff computes the delta, formats Markdown.
• diff.md is written to a host-mounted /output directory.
• (In GitHub Actions) a final step uses GitHub CLI to post the diff.md as a PR comment.
c. Architectural patterns / design principles
• Single-responsibility modules in pkg/ (e.g., pkg/diff, pkg/git, pkg/k8s).
• Dependency inversion: CLI code (cmd/) orchestrates high-level flow using pkg/.
• Side-effect isolation: all work happens in a throwaway cluster/container; no real cluster or Argo CD access needed.
• Declarative infra: cluster provisioning via code (k3d/kind), Argo CD install via Helm.
d. Technologies / frameworks
• Go modules / Go CLI
• Docker (for container) & host Docker socket
• Kind / k3d / Minikube (cluster provisioning)
• Helm (Argo CD install, argocd-config values)
• Argo CD API / CLI libraries (pkg/argocd)
• GitHub Actions & GitHub CLI (CI integration)
• MkDocs (documentation site)