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

Restore/install the tools through the Debian host bootstrap:

ansible-playbook -K -i bootstrap/host/inventory.ini bootstrap/host/playbook.yml

Then initialize the age identity and local SOPS config on the Debian host:

./jeannie secrets-init

secrets-init installs missing age/sops packages when needed, generates ~/.config/sops/age/keys.txt if it does not already exist, and writes .sops.yaml from .sops.yaml.example with the public recipient from that key. The public recipient in .sops.yaml is not sensitive and should be committed. The private identity in ~/.config/sops/age/keys.txt must stay outside Git.

Validate the current repo secret state:

./jeannie secrets-check

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.

Git Rules

• Commit .sops.yaml after ./jeannie secrets-init creates it.
• Commit only encrypted files matching *.secret.yaml, *.enc.yaml, *.secret.json, or *.enc.json.
• Do not commit ~/.config/sops/age/keys.txt, .age-key.txt, sops-age.key, or decrypted scratch files such as *.dec.yaml, *.decrypted.yaml, and *.plain.yaml.
• Run ./jeannie secrets-check before pushing a change that adds or edits encrypted secrets.