From 6bb9c77a8225c6c2ecc822006565701529f56a24 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Feb 2026 05:17:27 +0000 Subject: [PATCH] Add CLAUDE.md with comprehensive codebase documentation Document the project architecture (three-controller design, CRDs), directory structure, build commands, testing workflows, key dependencies, and development conventions for AI assistants working on this codebase. https://claude.ai/code/session_016QCVChhEZLuYZbhcfxyCzw --- CLAUDE.md | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..dd5b29d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,153 @@ +# CLAUDE.md — git-k8s + +## Project Overview + +git-k8s is a Kubernetes-native controller system for managing Git repositories and automated Git operations. It provides four Custom Resource Definitions (CRDs) and three controllers that enable declarative Git workflows within a Kubernetes cluster. + +**Module:** `github.com/imjasonh/git-k8s` +**Language:** Go 1.24.7 +**License:** Apache-2.0 + +## Architecture + +### Three-Controller Design + +1. **Push Controller** (`cmd/push-controller/`) — Watches `GitPushTransaction` resources, clones repos into memory using go-git, executes atomic pushes, and updates transaction status through phases (Pending → InProgress → Succeeded/Failed). + +2. **Sync Controller** (`cmd/sync-controller/`) — Watches `GitRepoSync` and `GitBranch` resources. Compares HEAD commits between two repos, calculates merge bases, and creates push transactions to keep branches synchronized. Marks as Conflicted when both sides have diverged. + +3. **Resolver Controller** (`cmd/resolver-controller/`) — Watches `GitRepoSync` resources in Conflicted phase. Performs automated 3-way merge with file-level conflict detection. Creates merge commits and push transactions to both repos. Falls back to `RequiresManualIntervention` on failure. + +### Custom Resources (CRDs) + +| CRD | Purpose | +|-----|---------| +| `GitRepository` | Defines a managed Git repo (clone URL, default branch, auth) | +| `GitBranch` | Tracks a branch within a repo (head commit, last updated) | +| `GitPushTransaction` | Atomic push operation with refspecs and CAS support | +| `GitRepoSync` | Two-way sync relationship between two repositories | + +CRD manifests live in `config/crds/`. + +### Key Packages + +| Package | Purpose | +|---------|---------| +| `pkg/apis/git/v1alpha1` | API type definitions, scheme registration, defaults | +| `pkg/client` | Hand-written typed client wrapper over Kubernetes dynamic client | +| `pkg/reconciler/internal` | Generic reconciler adapter (`KindReconciler[T]` interface) | +| `pkg/reconciler/push` | Push transaction reconciliation logic | +| `pkg/reconciler/sync` | Repo sync reconciliation logic | +| `pkg/reconciler/resolver` | Conflict resolution via 3-way merge | + +## Directory Structure + +``` +cmd/ # Controller entry points + push-controller/ + sync-controller/ + resolver-controller/ +pkg/ + apis/git/v1alpha1/ # CRD types, scheme, defaults, deepcopy + client/ # Typed client wrapper (manual, not generated) + reconciler/ + internal/ # Shared reconciler adapter pattern + push/ # Push transaction controller + reconciler + sync/ # Sync controller + reconciler + resolver/ # Conflict resolver controller + reconciler +config/ + crds/ # CRD YAML manifests + rbac/ # RBAC role definitions + deployments/ # Controller deployment manifests + core/ # Supporting infrastructure (Gitea) +test/e2e/ # End-to-end tests (build tag: e2e) +hack/ # Code generation scripts +``` + +## Build & Development + +### Prerequisites + +- Go 1.24.7+ +- `ko` (for container image builds) +- A Kubernetes cluster (KinD for local development) +- `kubectl` + +### Common Commands + +```bash +# Build all controller binaries +go build ./cmd/push-controller/ +go build ./cmd/sync-controller/ +go build ./cmd/resolver-controller/ + +# Run unit tests +go test ./... + +# Run linting +go vet ./... + +# Verify module tidiness +go mod tidy + +# Build and deploy to a cluster with ko +ko apply -f config/deployments/ + +# Install CRDs +kubectl apply -f config/crds/ +``` + +### E2E Tests + +E2E tests require a running Kubernetes cluster with Gitea deployed. They are gated behind a build tag: + +```bash +GITEA_URL=http://localhost:3000 \ +GITEA_INTERNAL_URL=http://gitea.git-system.svc.cluster.local:3000 \ + go test -v -count=1 -timeout=10m -tags=e2e ./test/e2e/ +``` + +Environment variables: +- `GITEA_URL` — External Gitea URL accessible from the test runner +- `GITEA_INTERNAL_URL` — In-cluster Gitea URL used by controllers + +## Key Dependencies + +- `github.com/go-git/go-git/v5` — All Git operations (clone, push, tree diffing, merge base) +- `k8s.io/client-go` — Kubernetes client (dynamic client as foundation) +- `k8s.io/apimachinery` — API types, serialization, scheme +- `knative.dev/pkg` — Controller lifecycle, injection, logging, leader election + +## Conventions & Patterns + +### Reconciler Pattern +Each controller follows the Knative `KindReconciler[T]` pattern: the generic adapter in `pkg/reconciler/internal` handles key splitting, resource fetching, and not-found handling. Developers implement only the `ReconcileKind(ctx, *T)` method with business logic. + +### Typed Client +The typed client in `pkg/client/` is hand-written over the Kubernetes dynamic client (not code-generated). It uses context-based injection (`client.WithClient`, `client.Get`). The `zz_generated.deepcopy.go` file is also hand-written. Both may be replaced with full code generation in the future. + +### Controller Separation +Each controller is a separate binary/deployment. Controllers communicate through Kubernetes resources — for example, the sync controller creates `GitPushTransaction` resources that the push controller then processes. + +### In-Memory Git Operations +All Git operations use `go-git` with `memory.NewStorage()`, keeping controllers stateless with no persistent volume requirements. + +### Status & Phase Management +Resources use phase-based state machines: +- **GitPushTransaction:** `Pending` → `InProgress` → `Succeeded` / `Failed` +- **GitRepoSync:** `InSync` / `Syncing` / `Conflicted` / `RequiresManualIntervention` + +### Labels & Ownership +Resources use labels (e.g., `git-k8s.imjasonh.com/repo-sync`) and owner references for resource relationships. No finalizers are used. + +### API Group +All CRDs are in the `git-k8s.imjasonh.com` API group, version `v1alpha1`. + +## CI/CD + +GitHub Actions (`.github/workflows/ci.yaml`) runs two jobs: + +1. **Build** — `go mod tidy` check, build all binaries, `go test ./...`, `go vet ./...` +2. **E2E** — Sets up KinD cluster, installs CRDs, deploys controllers via `ko`, deploys Gitea, runs e2e tests with `-tags=e2e` + +Container images use `ko` with a `gcr.io/distroless/static:nonroot` base image (configured in `.ko.yaml`).