sops-secrets

Secrets with sops and age

Encrypted secrets live in git next to their configuration. Use environment variables or FIFOs for runtime delivery; interactive editing can write temporary plaintext. gitleaks scans for leaked credentials, and cloud-run owns runtime Secret Manager integration.

Model

• age provides the key pair: one private key per machine or human, public recipients everywhere; prefer it for solo use. Choose cloud KMS when centrally managed access is required; adding a KMS recipient alongside age does not revoke the independent age decryption path.
• Name encrypted files *.enc.*: 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.
• Declare encryption policy in .sops.yaml: .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

Before the first encryption on a machine, and for any recipient change, follow key-lifecycle: preserve an existing SOPS_AGE_KEY_FILE or key, generate only when absent, distribute only public recipients, back up the private key outside Git, and rotate through updatekeys plus rotate.

Commands

sops edit secrets.enc.yaml                          # create or edit: decrypts to $EDITOR, re-encrypts on save
sops encrypt --filename-override config.enc.yaml --output config.enc.yaml config.yaml  # suffix selects the rule; --output preserves prior ciphertext if encryption fails
sops exec-env secrets.enc.env 'mise run watch'      # inject as env vars, memory-only (preferred)
sops exec-file secrets.enc.json 'tool --config {}'  # Unix tools get a FIFO by default, not a tmpfs guarantee

• Prefer exec-env and exec-file for runtime delivery; keep values out of logs and inspect how child processes handle them. --no-fifo writes a regular temporary file.
• Pipe decryption only to a reviewed consumer: bare sops decrypt prints plaintext secrets into captured output. Never display its stdout or redirect it to a plaintext file.
• Wire integrations from their guide: read integrations.md before wiring CI decryption (age key versus gcp_kms through Workload Identity Federation), Flux, OpenTofu, or a runtime secret manager.