SOPS + age Secrets Management

Encrypt secrets in git with SOPS using age keys. Values are encrypted with AES256-GCM; keys are simple X25519 keypairs.

Quick Reference

Task	Command
Generate age key	age-keygen -o keys.txt
Extract public key	age-keygen -y keys.txt
Encrypt file	sops encrypt file.yaml > file.enc.yaml
Decrypt file	sops decrypt file.enc.yaml
Edit encrypted file	sops edit file.enc.yaml
Update recipients	sops updatekeys -y file.enc.yaml
Rotate data key	sops rotate -i file.enc.yaml

Initial Setup

1. Generate Keys

# Create key directory
mkdir -p ~/.config/sops/age

# Generate keypair
age-keygen -o ~/.config/sops/age/keys.txt
# Output: public key: age1abc123...

2. Create .sops.yaml

At repository root:

creation_rules:
  - age: age1yourpublickeyhere...

3. Encrypt First File

sops encrypt config/secrets.yaml > config/secrets.enc.yaml
rm config/secrets.yaml
git add config/secrets.enc.yaml .sops.yaml

Core Workflows

Encrypt New File

# Create plaintext file
cat > secrets.yaml << 'EOF'
database:
  password: secret123
api_key: abc-xyz
EOF

# Encrypt (uses .sops.yaml rules)
sops encrypt secrets.yaml > secrets.enc.yaml
rm secrets.yaml

Edit Encrypted File

# Opens decrypted in $EDITOR, re-encrypts on save
sops edit secrets.enc.yaml

Decrypt for Use

# To stdout
sops decrypt secrets.enc.yaml

# To file
sops decrypt secrets.enc.yaml > secrets.yaml

# Extract single value
sops decrypt --extract '["database"]["password"]' secrets.enc.yaml

Pass to Process (No File)

# As environment variables
sops exec-env secrets.enc.yaml './deploy.sh'

# As temporary file
sops exec-file secrets.enc.yaml 'source {}'

Multi-Environment Configuration

# .sops.yaml
creation_rules:
  # Production - admin + CI only
  - path_regex: ^config/secrets/prod\..*
    age: >-
      age1admin...,
      age1cicd...

  # Staging/Dev - broader access
  - path_regex: ^config/secrets/.*
    age: >-
      age1admin...,
      age1cicd...,
      age1dev...

Selective Encryption

Only encrypt sensitive keys (keeps file readable):

creation_rules:
  - age: age1...
    encrypted_regex: ^(password|secret|token|key|api_key|private)$

Result:

database:
  host: localhost           # plaintext
  password: ENC[AES256_GCM,data:...,type:str]  # encrypted

CI/CD Integration

GitHub Actions

- name: Decrypt secrets
  env:
    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
  run: sops decrypt config/secrets.enc.yaml > secrets.yaml

Store AGE-SECRET-KEY-1... in repository secrets as SOPS_AGE_KEY.

Environment Variables

# Key file location
export SOPS_AGE_KEY_FILE=/path/to/keys.txt

# Key value directly (CI/CD)
export SOPS_AGE_KEY="AGE-SECRET-KEY-1..."

Key Management

Add New Recipient

1. Update .sops.yaml with new public key
2. Re-encrypt existing files:

   sops updatekeys -y file.enc.yaml
   

Remove Recipient

1. Remove from .sops.yaml
2. Re-encrypt and rotate:

   sops updatekeys -y file.enc.yaml
   sops rotate -i file.enc.yaml
   

Key Locations

Platform	Default Path
Linux	~/.config/sops/age/keys.txt
macOS	~/Library/Application Support/sops/age/keys.txt

Reference Files

File	When to Read
age-keys.md	Key generation, storage, distribution patterns
sops-config.md	.sops.yaml syntax, path rules, key groups
cli-reference.md	Full command reference, all flags
ci-cd-patterns.md	GitHub Actions, GitLab CI, Docker integration
troubleshooting.md	Common errors and solutions

Common Issues

Problem	Solution
"could not decrypt data key"	Wrong key - check SOPS_AGE_KEY_FILE or key location
"no matching keys found"	File uses Shamir key groups - need multiple keys
.sops.yaml not found	Run from repo root or ensure file is in parent directory
path_regex not matching	Use regex syntax (.*\.yaml$), not glob (*.yaml)

Security Notes

• Never commit private keys - Add keys.txt, *.agekey to .gitignore
• Use dedicated CI keys - Easier to rotate, limit scope
• Rotate data keys - Run sops rotate periodically
• Limit recipients - Production files should have minimal access

Official Documentation

Topic	URL
SOPS	https://getsops.io/docs/
SOPS GitHub	https://github.com/getsops/sops
age	https://github.com/FiloSottile/age