feat(fastdeploy): git-webhook → Decofile CR → KV-sync Job

Operator-owned, CR-driven fast deploy for content (.deco/blocks). Two pluggable
interfaces (internal/deploy):
- DeploymentTarget: maps a git push to desired-state CRs. cloudflare-workers impl
  resolves the repo's Deco CR and emits a Decofile CR (target: tanstack-kv) on a
  content-only push to a fast-deploy-enabled site.
- FastDeployment: drives a Decofile CR to its effect. tanstack-kv impl creates a
  self-cleaning batch/v1 Job (decofile-syncer image) that pushes the decofile to
  Cloudflare KV; the existing ConfigMap/Knative path stays the default.

Adds POST /webhooks/github (HMAC-verified, outside basic-auth) to the operator
API; Decofile CRD gains target/tanstackKV; Deco CRD gains fastDeploy; Decofile
reconciler dispatches non-configmap targets and owns Jobs (batch RBAC).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hugo-ccabral

api/v1alpha1/deco_types.go

@@ -35,6 +35,33 @@ type DecoSpec struct {
 	// Admin adds entries to Previews.Active on PR open and removes on PR close.
 	// +optional
 	Previews *DecoPreviewPolicy `json:"previews,omitempty"`
+
+	// FastDeploy enables and configures git-driven, KV-first content fast-deploy
+	// for this site. When Enabled, content-only pushes (touching only
+	// .deco/blocks/**) sync to Cloudflare KV via a Decofile CR instead of a full
+	// build/deploy. This is the per-site config the webhook's DeploymentTarget
+	// reads to decide whether and how to fast-deploy.
+	// +optional
+	FastDeploy *DecoFastDeploy `json:"fastDeploy,omitempty"`
+}
+
+// DecoFastDeploy configures KV-first content fast-deploy for a site.
+// +kubebuilder:validation:XValidation:rule="!self.enabled || (has(self.kvNamespaceId) && size(self.kvNamespaceId) > 0)",message="kvNamespaceId is required when fastDeploy is enabled"
+type DecoFastDeploy struct {
+	// Enabled gates the fast-deploy content path. When false, content pushes take
+	// the normal build/deploy path.
+	// +optional
+	Enabled bool `json:"enabled,omitempty"`
+
+	// KVNamespaceID is the Cloudflare KV namespace id for this site (one per site).
+	// Required when enabled (enforced via the XValidation rule on this struct).
+	// +optional
+	KVNamespaceID string `json:"kvNamespaceId,omitempty"`
+
+	// SiteOrigin is the deployed site origin used for cache purge after a sync
+	// (e.g. https://www.example.com). Optional.
+	// +optional
+	SiteOrigin string `json:"siteOrigin,omitempty"`
 }
 
 // DecoEnvVar is a plain environment variable injected into the build Job.

api/v1alpha1/decofile_types.go

@@ -24,7 +24,24 @@ import (
 // EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
 // NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
 
+// Decofile source kinds (DecofileSpec.Source).
+const (
+	SourceInline = "inline"
+	SourceGitHub = "github"
+)
+
+// Decofile delivery targets (DecofileSpec.Target) — selects the FastDeployment
+// strategy that reconciles the CR.
+const (
+	// TargetConfigMap writes a ConfigMap + notifies Knative pods (default).
+	TargetConfigMap = "configmap"
+	// TargetTanstackKV runs a Job that pushes the decofile to Cloudflare KV.
+	TargetTanstackKV = "tanstack-kv"
+)
+
 // DecofileSpec defines the desired state of Decofile.
+// +kubebuilder:validation:XValidation:rule="self.target != 'tanstack-kv' || has(self.tanstackKV)",message="spec.tanstackKV is required when target is tanstack-kv"
+// +kubebuilder:validation:XValidation:rule="self.target != 'tanstack-kv' || self.source == 'github'",message="source must be 'github' when target is tanstack-kv"
 type DecofileSpec struct {
 	// Source specifies where to get the configuration data
 	// +kubebuilder:validation:Required
@@ -43,6 +60,33 @@ type DecofileSpec struct {
 	// Pods are queried using the app.deco/deploymentId label
 	// +optional
 	DeploymentId string `json:"deploymentId,omitempty"`
+
+	// Target selects how this Decofile is delivered (the FastDeployment strategy).
+	// "configmap" (default) writes a ConfigMap and notifies Knative pods.
+	// "tanstack-kv" runs a self-cleaning Job that pushes the decofile to Cloudflare
+	// KV — the fast-deploy content path for TanStack/Workers sites.
+	// +kubebuilder:validation:Enum=configmap;tanstack-kv
+	// +kubebuilder:default=configmap
+	// +optional
+	Target string `json:"target,omitempty"`
+
+	// TanstackKV configures the tanstack-kv target. Required when target=tanstack-kv.
+	// The repo/commit to sync come from spec.github (source=github).
+	// +optional
+	TanstackKV *TanstackKVTarget `json:"tanstackKV,omitempty"`
+}
+
+// TanstackKVTarget configures Cloudflare KV fast-deploy for a TanStack/Workers site.
+type TanstackKVTarget struct {
+	// KVNamespaceID is the Cloudflare KV namespace id for this site (one per site).
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinLength=1
+	KVNamespaceID string `json:"kvNamespaceId"`
+
+	// SiteOrigin is the deployed site origin used to POST /_cache/purge after the
+	// sync (e.g. https://www.example.com). Optional — purge is skipped when empty.
+	// +optional
+	SiteOrigin string `json:"siteOrigin,omitempty"`
 }
 
 // InlineSource contains direct JSON configuration data
@@ -98,6 +142,10 @@ type DecofileStatus struct {
 	// GitHubCommit stores the commit SHA if using GitHub source
 	// +optional
 	GitHubCommit string `json:"githubCommit,omitempty"`
+
+	// JobName is the K8s Job name for the current tanstack-kv sync (target=tanstack-kv).
+	// +optional
+	JobName string `json:"jobName,omitempty"`
 }
 
 // +kubebuilder:object:root=true

api/v1alpha1/zz_generated.deepcopy.go

@@ -2,7 +2,7 @@ apiVersion: v2
 name: deco-operator
 description: Kubernetes operator for Deco CMS that manages Decofile resources and automatically injects configuration into Knative Services
 type: application
-version: 0.2.6
+version: 0.3.0
 appVersion: "0.2.6"
 keywords:
   - operator

chart/Chart.yaml

@@ -47,7 +47,7 @@ spec:
         command:
         - /manager
         image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
-        {{- if or (and .Values.github (or .Values.github.token .Values.github.existingSecret)) .Values.operatorApi.existingSecret (and .Values.valkey (get .Values.valkey "sentinelUrls")) .Values.cfworkers.existingSecret .Values.cfworkers.builderImage .Values.cfworkers.artifactsBucket .Values.s3.region .Values.s3.logsBucket .Values.s3.stateBucket .Values.build.serviceAccount .Values.build.roleArn .Values.build.nodeSelector .Values.build.tolerations }}
+        {{- if or (and .Values.github (or .Values.github.token .Values.github.existingSecret)) .Values.operatorApi.existingSecret (and .Values.valkey (get .Values.valkey "sentinelUrls")) .Values.cfworkers.existingSecret .Values.cfworkers.builderImage .Values.cfworkers.artifactsBucket .Values.s3.region .Values.s3.logsBucket .Values.s3.stateBucket .Values.build.serviceAccount .Values.build.roleArn .Values.build.nodeSelector .Values.build.tolerations (and .Values.fastDeploy .Values.fastDeploy.syncerImage) }}
         env:
         {{- if and .Values.github .Values.github.existingSecret }}
         - name: GITHUB_TOKEN
@@ -131,19 +131,35 @@ spec:
           value: {{ .tolerations | toJson | quote }}
         {{- end }}
         {{- end }}
+        {{- with .Values.fastDeploy }}
+        {{- if .syncerImage }}
+        - name: DECOFILE_SYNCER_IMAGE
+          value: {{ .syncerImage | quote }}
+        {{- end }}
+        {{- end }}
         {{- if .Values.operatorApi.existingSecret }}
         {{- if .Values.operatorApi.addr }}
         - name: OPERATOR_API_ADDR
           value: {{ .Values.operatorApi.addr | quote }}
         {{- end }}
         {{- end }}
         {{- end }}
-        {{- if .Values.operatorApi.existingSecret }}
+        {{- if or .Values.secretEnv.existingSecret .Values.operatorApi.existingSecret }}
         envFrom:
+        {{- if .Values.secretEnv.existingSecret }}
+        # Unified operator secret: keys ARE env var names (CLOUDFLARE_*, GITHUB_*,
+        # etc.), injected wholesale — add a new secret env by adding a key to the
+        # backing ExternalSecret, no chart change needed.
+        - secretRef:
+            name: {{ .Values.secretEnv.existingSecret | quote }}
+            optional: true
+        {{- end }}
+        {{- if .Values.operatorApi.existingSecret }}
         - secretRef:
             name: {{ .Values.operatorApi.existingSecret | quote }}
             optional: true
         {{- end }}
+        {{- end }}
         livenessProbe:
           httpGet:
             path: /healthz

chart/templates/deployment-operator-controller-manager.yaml

@@ -123,6 +123,24 @@ build:
   nodeSelector: {}      # Default nodeSelector for build pods (overridable per-site via spec.build.nodeSelector)
   tolerations: []       # Default tolerations for build pods (overridable per-site via spec.build.tolerations)
 
+# ── Unified secret env ───────────────────────────────────────────────────────
+# A single Secret whose KEYS ARE THE ENV VAR NAMES (e.g. CLOUDFLARE_API_WORKERS_TOKEN,
+# CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_KV_API_TOKEN, GITHUB_TOKEN, GITHUB_APP_ID,
+# GITHUB_APP_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET, DECO_PURGE_TOKEN). Injected
+# wholesale via envFrom, so adding a new secret env is just a new key on the
+# backing ExternalSecret — no chart change. Preferred over the per-feature
+# existingSecret knobs above; those still work when set (and win, being explicit env).
+secretEnv:
+  existingSecret: ""
+
+# ── Fast deploy (KV-first content) ───────────────────────────────────────────
+# Git-webhook → Decofile CR → self-cleaning KV-sync Job. The webhook/KV/GitHub-App
+# secrets come from secretEnv above (GITHUB_WEBHOOK_SECRET enables the endpoint;
+# the operator-api controller must also be enabled). Only the non-secret syncer
+# image lives here.
+fastDeploy:
+  syncerImage: ""            # decofile-syncer image (repository:tag) → DECOFILE_SYNCER_IMAGE
+
 # ── Operator Management API ──────────────────────────────────────────────────
 # General HTTP API for managing operator resources (DecoRedirects, etc.).
 # Enabled when username+password (or existingSecret) are set.

chart/values.yaml

@@ -50,6 +50,8 @@ import (
 	"github.com/deco-sites/decofile-operator/internal/api"
 	"github.com/deco-sites/decofile-operator/internal/build"
 	"github.com/deco-sites/decofile-operator/internal/controller"
+	"github.com/deco-sites/decofile-operator/internal/deploy"
+	"github.com/deco-sites/decofile-operator/internal/githubapp"
 	"github.com/deco-sites/decofile-operator/internal/valkey"
 	webhookv1 "github.com/deco-sites/decofile-operator/internal/webhook/v1"
 	// +kubebuilder:scaffold:imports
@@ -336,10 +338,30 @@ func main() {
 
 	if enabled(controller.DecofileControllerName) {
 		httpClient := controller.NewHTTPClient()
+		// Fast-deploy: pluggable FastDeployment strategies for non-configmap
+		// Decofile targets. tanstack-kv runs a self-cleaning Job that pushes the
+		// decofile to Cloudflare KV (config from env; inert unless a Decofile
+		// selects the target).
+		fastDeployRegistry := deploy.NewDeploymentRegistry()
+		tkvCfg := deploy.TanstackKVConfigFromEnv()
+		// Private-repo clones use a GitHub App installation token (short-lived,
+		// repo-scoped) — same mechanism as admin. Optional: falls back to a static
+		// GITHUB_TOKEN / public-repo clone when unset.
+		if ghApp, gerr := githubapp.NewFromEnv(); gerr != nil {
+			setupLog.Error(gerr, "GitHub App disabled: invalid GITHUB_APP_* config; private-repo fast-deploy will fail")
+		} else if ghApp != nil {
+			tkvCfg.GitHubApp = ghApp
+			setupLog.Info("GitHub App configured for fast-deploy private-repo clones")
+		}
+		fastDeployRegistry.Register(
+			decositesv1alpha1.TargetTanstackKV,
+			deploy.NewTanstackKV(tkvCfg),
+		)
 		if err = (&controller.DecofileReconciler{
 			Client:     mgr.GetClient(),
 			Scheme:     mgr.GetScheme(),
 			HTTPClient: httpClient,
+			FastDeploy: fastDeployRegistry,
 		}).SetupWithManager(mgr); err != nil {
 			setupLog.Error(err, "unable to create controller", "controller", "Decofile")
 			os.Exit(1)
@@ -404,13 +426,25 @@ func main() {
 	if enabled(api.ControllerName) {
 		apiUser := os.Getenv("OPERATOR_API_USER")
 		apiPass := os.Getenv("OPERATOR_API_PASSWORD")
-		if apiUser != "" && apiPass != "" {
+
+		// Git webhook → fast-deploy. The cloudflare-workers DeploymentTarget turns a
+		// content-only push into a Decofile CR. Authenticated by HMAC signature
+		// (GITHUB_WEBHOOK_SECRET), independent of the basic-auth redirects API.
+		targetRegistry := deploy.NewTargetRegistry()
+		targetRegistry.Register(deploy.ServingCloudflareWorker, deploy.NewCloudflareWorkersTarget())
+		webhookHandlers := api.NewWebhookHandlers(
+			mgr.GetClient(), os.Getenv("GITHUB_WEBHOOK_SECRET"), targetRegistry,
+		)
+
+		// Start the HTTP server when EITHER the redirects API (basic-auth creds) or
+		// the webhook (secret) is configured.
+		if (apiUser != "" && apiPass != "") || webhookHandlers.Enabled() {
 			h := api.NewHandlers(mgr.GetClient(), redirectNamespace)
-			if err = mgr.Add(api.NewServer(operatorAPIAddr, apiUser, apiPass, h)); err != nil {
+			if err = mgr.Add(api.NewServer(operatorAPIAddr, apiUser, apiPass, h, webhookHandlers)); err != nil {
 				setupLog.Error(err, "unable to add operator API server")
 				os.Exit(1)
 			}
-			setupLog.Info("Operator API enabled", "addr", operatorAPIAddr)
+			setupLog.Info("Operator API enabled", "addr", operatorAPIAddr, "webhook", webhookHandlers.Enabled())
 		}
 	}
 

cmd/main.go

@@ -90,9 +90,43 @@ spec:
                 - inline
                 - github
                 type: string
+              tanstackKV:
+                description: |-
+                  TanstackKV configures the tanstack-kv target. Required when target=tanstack-kv.
+                  The repo/commit to sync come from spec.github (source=github).
+                properties:
+                  kvNamespaceId:
+                    description: KVNamespaceID is the Cloudflare KV namespace id for
+                      this site (one per site).
+                    minLength: 1
+                    type: string
+                  siteOrigin:
+                    description: |-
+                      SiteOrigin is the deployed site origin used to POST /_cache/purge after the
+                      sync (e.g. https://www.example.com). Optional — purge is skipped when empty.
+                    type: string
+                required:
+                - kvNamespaceId
+                type: object
+              target:
+                default: configmap
+                description: |-
+                  Target selects how this Decofile is delivered (the FastDeployment strategy).
+                  "configmap" (default) writes a ConfigMap and notifies Knative pods.
+                  "tanstack-kv" runs a self-cleaning Job that pushes the decofile to Cloudflare
+                  KV — the fast-deploy content path for TanStack/Workers sites.
+                enum:
+                - configmap
+                - tanstack-kv
+                type: string
             required:
             - source
             type: object
+            x-kubernetes-validations:
+            - message: spec.tanstackKV is required when target is tanstack-kv
+              rule: self.target != 'tanstack-kv' || has(self.tanstackKV)
+            - message: source must be 'github' when target is tanstack-kv
+              rule: self.target != 'tanstack-kv' || self.source == 'github'
           status:
             description: DecofileStatus defines the observed state of Decofile.
             properties:
@@ -161,6 +195,10 @@ spec:
               githubCommit:
                 description: GitHubCommit stores the commit SHA if using GitHub source
                 type: string
+              jobName:
+                description: JobName is the K8s Job name for the current tanstack-kv
+                  sync (target=tanstack-kv).
+                type: string
               lastUpdated:
                 description: LastUpdated is the timestamp of the last update
                 format: date-time