DevRunbook-Public/adr/ADR-005-integration-secrets.md

ADR-005 — Versioned application-level encryption for integration secrets

Status

Accepted

Context

Gitea tokens must be stored for background synchronization but must not appear in prompts, logs or ordinary backups.

Decision

Encrypt integration secrets with an externally supplied versioned master key. Store encrypted values and safe metadata in PostgreSQL. Return only write-only/rotatable secret controls to the UI.

Consequences

• database compromise alone does not reveal tokens;
• key backup and rotation become operator responsibilities;
• losing the key makes stored tokens unrecoverable;
• future external secret-provider adapters can implement the same port.