feat(deploy): wire Stripe credentials through ExternalSecrets, gated off

k8s/helm/commonly/templates/core/backend-deployment.yaml

@@ -356,6 +356,35 @@ spec:
               key: deepgram-api-key
               optional: true
 
+        # Billing (Stripe). Deliberately NOT gated on billing.enabled — every
+        # ref is `optional: true`, so when the flag is off the keys are simply
+        # absent and the backend reports billing_not_configured. Keeping these
+        # unconditional means turning billing on is a one-line values change
+        # with no deployment-template edit to forget.
+        #
+        # STRIPE_SECRET_KEY is the flag the code actually reads: billingService
+        # .STRIPE_ENABLED() is Boolean(process.env.STRIPE_SECRET_KEY), so an
+        # absent key disables checkout, portal AND the webhook together. There
+        # is no state where we accept a webhook we cannot verify.
+        - name: STRIPE_SECRET_KEY
+          valueFrom:
+            secretKeyRef:
+              name: api-keys
+              key: stripe-secret-key
+              optional: true
+        - name: STRIPE_WEBHOOK_SECRET
+          valueFrom:
+            secretKeyRef:
+              name: api-keys
+              key: stripe-webhook-secret
+              optional: true
+        - name: STRIPE_PRICE_ID
+          valueFrom:
+            secretKeyRef:
+              name: api-keys
+              key: stripe-price-id
+              optional: true
+
         # LiteLLM Configuration
         - name: LITELLM_MASTER_KEY
           valueFrom:

k8s/helm/commonly/templates/secrets/api-keys.yaml

@@ -43,6 +43,23 @@ spec:
       key: commonly-dev-sentry-dsn
   {{- end }}
 
+  {{- if .Values.billing.enabled }}
+  # Billing (Stripe). Same gating rule as error tracking above: ESO rejects the
+  # entire ExternalSecret when any referenced remote key is missing, so all
+  # three must exist WITH a version in Secret Manager before this flag flips.
+  # The price id is not secret, but it lives here so swapping test -> live is a
+  # `gcloud secrets versions add`, not a chart edit and redeploy.
+  - secretKey: stripe-secret-key
+    remoteRef:
+      key: commonly-dev-stripe-secret-key
+  - secretKey: stripe-webhook-secret
+    remoteRef:
+      key: commonly-dev-stripe-webhook-secret
+  - secretKey: stripe-price-id
+    remoteRef:
+      key: commonly-dev-stripe-price-id
+  {{- end }}
+
   # Discord Integration
   - secretKey: discord-bot-token
     remoteRef:

k8s/helm/commonly/values-dev.yaml

@@ -8,6 +8,13 @@ global:
 errorTracking:
   enabled: true
 
+# All three commonly-dev-stripe-* secrets verified present with an ENABLED
+# version on 2026-08-06 before this was flipped. Do not set true anywhere the
+# secrets are absent: an empty secret container passes `describe` and still
+# breaks the whole api-keys ExternalSecret. See the note in values.yaml.
+billing:
+  enabled: true
+
 agentProvisioning:
   enabled: true
   createWorkspacePvc: false

k8s/helm/commonly/values.yaml

@@ -18,6 +18,22 @@ createNamespace: true
 errorTracking:
   enabled: false
 
+# Paid tier (Stripe). Opt-in, and OFF by default so self-hosted deployments
+# never reach for billing credentials they do not have.
+#
+# Flipping this to true makes the api-keys ExternalSecret reference three
+# remote keys — commonly-dev-stripe-{secret-key,webhook-secret,price-id}. ESO
+# rejects the WHOLE ExternalSecret when any referenced key is missing, so every
+# other secret in it (JWT, LiteLLM, OAuth) would stop syncing too. Populate all
+# three in Secret Manager BEFORE enabling. `gcloud secrets versions list <name>`
+# must show at least one version for each; an empty secret container is not
+# enough.
+#
+# The backend degrades honestly when this is off: STRIPE_SECRET_KEY is absent,
+# so /api/billing/* returns 503 billing_not_configured rather than half-working.
+billing:
+  enabled: false
+
 # Agent provisioning (RBAC + PVCs)
 agentProvisioning:
   enabled: true