---

name: sops-age-secrets description: | SOPS and age encryption for secrets management in git repositories. Use when: (1) Setting up encrypted secrets in a project (initial .sops.yaml configuration) (2) Encrypting/decrypting YAML, JSON, ENV, or INI files with age keys (3) Managing age keys (generation, distribution, rotation) (4) Configuring path-based encryption rules for different environments (5) Integrating SOPS decryption in CI/CD pipelines (GitHub Actions, GitLab CI) (6) Troubleshooting SOPS decryption failures or key issues (7) Selective encryption with encrypted_regex patterns

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

Initial Setup

1. Generate Keys

Copy# 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:

Copycreation_rules:
  - age: age1yourpublickeyhere...

3. Encrypt First File

Copysops 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

Copy# 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

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

Decrypt for Use

Copy# 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)

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

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

Multi-Environment Configuration

Copy# .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):

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

Result:

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

CI/CD Integration

GitHub Actions

Copy- 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

Copy# 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:

   Copysops updatekeys -y file.enc.yaml
   

Remove Recipient

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

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

Key Locations

Reference Files

Common Issues

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