my-homelab-configs/docs/secrets.md

Secret Management

This repo uses SOPS with age for secrets that must be stored in Git. The encrypted files can be committed, while the age private key stays on the Debian homelab server or in a deliberately scoped CI secret.

First-Time Setup

Install the tools on the Debian host:

sudo apt-get update
sudo apt-get install -y --no-install-recommends age sops

Generate the local age identity:

mkdir -p ~/.config/sops/age
age-keygen -o ~/.config/sops/age/keys.txt
grep '^# public key:' ~/.config/sops/age/keys.txt

Copy .sops.yaml.example to .sops.yaml, replace the placeholder recipient with the printed public key, and commit .sops.yaml. The public recipient is not sensitive; the private identity in ~/.config/sops/age/keys.txt is.

File Naming

Use one of these suffixes for encrypted YAML:

*.secret.yaml
*.enc.yaml

For Kubernetes Secret manifests, keep sensitive values under stringData or data so the example encrypted_regex encrypts the right fields without obscuring resource metadata needed by Argo CD and review diffs.

Editing

Create or edit an encrypted file:

SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txt sops apps/example/app.secret.yaml

Check the decrypted render locally without writing it to the repo:

SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txt sops -d apps/example/app.secret.yaml

Decrypted scratch files are intentionally ignored by .gitignore; encrypted files are not.