secrets

Cloudflare Workers Secrets

Single source of truth = GitHub repo secret。所有 worker runtime 用的 secret 一律走 GitHub Actions + cloudflare/wrangler-action@v3 的 secrets: input 推進 worker。

MUST

• MUST 把所有 runtime secret 設在 GitHub repo secret，naming 對齊 STAGING_<NAME> / PRODUCTION_<NAME>（per-env）或 <NAME>（cross-env shared，限非敏感如 OAuth client id）
• MUST 在 deploy-{staging,production}.yml 用 cloudflare/wrangler-action@v3 並透過 secrets: | list + env: block 把 GitHub secret 推進 worker
• MUST 對應 worker runtime env 名稱（不帶 STAGING_ / PRODUCTION_ 前綴）— GitHub secret 帶前綴、worker runtime 不帶
• MUST rotation 只動 GitHub Secret（gh secret set），下次 deploy workflow 自動 sync 進 worker
• MUST 把 secret 值寫進 Notion「GitHub Secrets & 環境變數」page（per consumer）。義務綁的是「收到明文的當下」，不是「改動 secret 值時」 —— 全文與唯一例外的措辭在 [[secret-custody]]，本條只是它在 Workers 面的入口

NEVER

• NEVER 手動跑 wrangler secret put <NAME> 設 production / staging worker secret — 繞過正規流程，rotation 會脫節
• NEVER 把 secret 寫進 wrangler.toml 的 [vars] 區塊 — [vars] 是 plaintext，會在 worker dashboard 可見且 commit 進 git
• NEVER 在 wrangler-action 之外的 workflow step 直接 echo secret 到 wrangler secret put — 同樣繞過 SoT，且 echo 容易 leak 進 log
• NEVER dev / staging / production 共用同一條 secret（rotation 風險：一漏全崩）— 每個 env 獨立生成

唯一例外

只在以下情況可手動跑 wrangler secret put：

• Bootstrap 初次 deploy 之前：worker 尚未存在、deploy workflow 還沒跑過第一次，需要手動 push 初始 secret 才能讓 first deploy 不 crash。第一次 deploy 後立即把 secret 加進 workflow secrets: list，後續 rotation 走正規流程
• 緊急 incident response：production secret 洩漏需立即 rotation，等不及下次 deploy。必同時 gh secret set 更新 GitHub Secret + 開 issue / 在 commit message 註記，下次 deploy 會 overwrite 同值

推送流程範例（ production）

# .github/workflows/deploy-production.yml
- uses: cloudflare/wrangler-action@v3
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    command: deploy --env production
    secrets: |
      EVLOG_AUDIT_SECRET     # ← secret name 在 worker runtime 看到的
      SUPABASE_SECRET_KEY
      ...
  env:
    EVLOG_AUDIT_SECRET: ${{ secrets.PRODUCTION_EVLOG_AUDIT_SECRET }}  # ← GitHub secret name
    SUPABASE_SECRET_KEY: ${{ secrets.PRODUCTION_SUPABASE_SECRET_KEY }}
    ...