Doctrine

Edge function local dev requires runtime secrets — never force seats into deploy-to-test cycles

ID: ORA-2026-0025
Date: 2026-04-17
Status: unknown
Maturity: M1
Source: docs/entries/doctrines/ORA-2026-0025_edge-function-local-dev-requires-runtime-secrets.md

code-qualityedge-functionscredentialslocal-dev

Edge function local dev requires runtime secrets — never force seats into deploy-to-test cycles

Rule

When a Codex seat works on a Supabase edge function that depends on third-party API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPGRAM_API_KEY, etc.), the seat MUST be able to run deno serve or supabase functions serve locally with those keys available.

Forcing a seat into a deploy → invoke → verify cycle when a local serve → invoke → verify cycle is possible wastes minutes per iteration and blocks fast feedback loops. The deploy path should be the final verification step, not the development loop.

The process gap

1. All runtime secrets exist in macOS Keychain (service orbit) — documented in CREDENTIALS_REGISTRY.md 2. Supabase edge functions read secrets from Deno.env.get() at runtime 3. .env.local is already gitignored in camber 4. Nobody creates .env.local when starting edge function work — this is the gap

Required setup for edge function development

Before running deno serve or supabase functions serve on any edge function that calls a third-party API, the seat must ensure a .env.local file exists at supabase/.env.local (or the worktree equivalent) containing the required runtime secrets.

Which functions need which secrets

Secret	Functions (as of 2026-04-17)
`OPENAI_API_KEY`	generate-summary, ai-router, journal-extract, chain-detect, segment-llm, embed-facts, evidence-assembler, decision-auditor, loop-closure, striking-detect, redline-assistant, audit-attribution, audit-attribution-reviewer, journal-consolidate, journal-embed-backfill
`ANTHROPIC_API_KEY`	chat-proxy
`DEEPGRAM_API_KEY`	transcribe-deepgram (also DB-backed)
`GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY`	financial-receipt-ingest
`X_EDGE_SECRET`	Any function calling another function (M2M auth)
`SUPABASE_URL`	Most functions (Supabase client init)
`SUPABASE_SERVICE_ROLE_KEY`	Most functions (privileged DB access)

Helper

~/Desktop/fleet/scripts/edge-fn-env generates a .env.local from Keychain for a given worktree or repo path. Usage:

edge-fn-env /path/to/camber/supabase
# Creates /path/to/camber/supabase/.env.local with all known edge function secrets

Anti-pattern — deploy-to-test as the default loop

When a seat says "I don't have X_KEY locally, so I'll deploy and invoke remotely," that's the signal this doctrine wasn't followed. The correct response is: pull the key from Keychain, write .env.local, then iterate locally.

Exception: some functions genuinely can't run locally (e.g., they depend on Supabase infra like Realtime or Storage that isn't available in deno serve). In those cases, deploy-to-test is legitimate — but document why in the ticket.

Enforcement

Codex seats: before starting edge function work, run edge-fn-env against your worktree
Code review: if a ticket mentions "deployed to test" on a function that could have run locally, flag the process gap
Credential registry: when adding a new third-party secret, add it to both the Keychain and the edge-fn-env script's manifest