Secrets at rest & key rotation
Entrepot stores some secrets in Postgres so they can be managed through the API: upstream proxy passwords, S3 secret access keys, scanner secrets (Trivy server token, webhook HMAC key), GitLab API tokens and repository signing keys. They are encrypted with AES-256-GCM before they reach the database, and the API treats them as write-only — they are never returned.
Sealed values carry a key ID (enc:v1:<kid>:…), so several keys can coexist
during a rotation.
The key
Section titled “The key”| Key | Env | Default |
|---|---|---|
secrets.key |
ENTREPOT_SECRETS_KEY (_FILE supported) |
derived from auth.sessionSecret |
secrets.previousKeys |
ENTREPOT_SECRETS_PREVIOUSKEYS (comma-separated) |
none |
- The key must be at least 32 bytes and identical on all replicas (and on scan workers).
- Without
secrets.key, a key derived fromauth.sessionSecretis used. Setting a dedicated key lets you rotate the session secret and the secrets key independently — recommended for production. - With the Helm chart, put the key under
secrets-keyinauth.existingSecret, or setsecrets.key.
Rotating the key
Section titled “Rotating the key”-
Generate a new key, e.g.
openssl rand -base64 48. -
Deploy with the new key as
secrets.keyand the old key insecrets.previousKeys:secrets:key: <new key>previousKeys: [<old key>]Old values stay readable through the previous key, and new values are sealed with the current one. At startup values are re-encrypted with the current key.
-
Once every replica runs with the new key and has started at least once, remove the old key from
previousKeysand roll out again.
If you never set secrets.key and want to rotate auth.sessionSecret, do
the same: set secrets.key to a new key and list the old session secret in
secrets.previousKeys, so the values sealed with the derived key can still
be opened. (Rotating the session secret also signs everyone out and
invalidates outstanding Docker registry tokens.)
Plain-text values from older versions
Section titled “Plain-text values from older versions”Values written before encryption was enabled are read as-is and re-sealed by the startup migration, so upgrading needs no manual step.