ADR-001 — Secret management
Status: Proposed · Date: 2026-06-26 · Deciders: Eng Lead, DevOps, Security · Tags: security, ops
Context
Phase 0 (Phase_0.md §Epic 0.E) requires a decided strategy for storing and distributing secrets (DB URIs, auth secrets, AI keys, S3 creds) across local / staging / production without ever committing them to git. Local dev uses .env.local (gitignored). Staging/prod need a managed store.
Decision
To be ratified at G0. Recommended default: Doppler for app-level secret distribution (simple per-env projects, CI integration, audit log), with cloud-native KMS (e.g. AWS KMS / GCP Secret Manager) as the encryption backstop once the hosting platform is fixed in ADR-002.
- Local:
.env.localonly; never committed. - CI: secrets injected as masked GitHub Actions secrets / Doppler service tokens.
- Staging/Prod: pulled at deploy/runtime from the managed store; no plaintext env on disk.
Alternatives considered
| Option | Pros | Cons | Why not (yet) |
|---|---|---|---|
| Doppler | Fast setup, good DX, audit, CI integration | SaaS dependency | — (leading choice) |
| 1Password Secrets Automation | Strong if org already on 1Password | Heavier setup | Revisit if org standard |
| HashiCorp Vault | Powerful, self-host | High ops burden for SMB scale | Overkill for v1 |
| Cloud KMS only | Native, cheap | Per-cloud lock-in; less DX for app envs | Use as backstop, not primary |
Consequences
- One documented path for all environments; reduces leak risk (threat model: secret leak).
- Decision is reversible — secrets are referenced by name, not platform-specific in app code.
- Revisit when ADR-002 fixes the hosting platform.