sops-secrets

Secrets with sops and age

Encrypted secrets live in git next to the code they configure and plaintext exists only in memory; gitleaks catches what was committed before encryption and cloud-run owns runtime secrets in Secret Manager.

Model

• age provides the key pair: one private key per machine or human, public recipients everywhere; prefer it over PGP and cloud KMS for solo use, adding a gcp_kms recipient only for team revocation.
• sops encrypts the values of YAML, JSON, and ENV files; keys stay readable, so diffs review cleanly and git log tells which secret changed, never what it is.
• Naming: encrypted files are committed as *.enc.yaml, *.enc.json, or *.enc.env; sops.yaml keys its rules off that suffix and plaintext siblings stay gitignored.
• Policy as file: .sops.yaml at the repo root (sops.yaml) declares which paths get encrypted and for which recipients, so no ad-hoc flags are needed.

Keys

1. Generate once per machine: age-keygen -o ~/.config/sops/age/keys.txt (sops' default key location); print the public half with age-keygen -y ~/.config/sops/age/keys.txt.
2. Distribute only the public key, as the age: recipient in each repo's .sops.yaml.
3. Back up the private key in a password manager; never commit it to any dotfiles repo.
4. Rotate: add the new recipient to .sops.yaml, run sops updatekeys <file> on every encrypted file, then remove the old recipient and repeat; sops rotate -i <file> re-keys the data key after an exposure.

Commands

sops edit secrets.enc.yaml                          # create or edit: decrypts to $EDITOR, re-encrypts on save
sops encrypt -i config.yaml                         # encrypt an existing file in place, then rename it *.enc.yaml
sops decrypt secrets.enc.yaml                       # decrypt to stdout for piping, never redirect to a file
sops exec-env secrets.enc.env 'mise run watch'      # inject as env vars, memory-only (preferred)
sops exec-file secrets.enc.json 'tool --config {}'  # tools that need a file path get a tmpfs one