SOPS Secrets in Git

SOPS cheatsheet — encrypt secrets in YAML, JSON, ENV files. sops -e to encrypt, sops -d to decrypt, sops edit to update in-place. Integrates with AWS KMS, GCP KMS, age.

6 min read

What it is

SOPS (Secrets OPerationS) is a tool for encrypting and decrypting secrets in configuration files, designed to be easily integrated into Git workflows.

Installation

Linux

# Using apt (Debian/Ubuntu)
sudo apt update && sudo apt install sops

# Using dnf (Fedora/CentOS/RHEL)
sudo dnf install sops

# Using pacman (Arch Linux)
sudo pacman -S sops

# Using Homebrew (if installed)
brew install sops

macOS

# Using Homebrew
brew install sops

Windows

# Using Chocolatey
choco install sops

# Using Scoop
scoop install sops

Core Concepts

  • Encrypted Files: SOPS encrypts entire files. The original file content is replaced with encrypted data, and the original content is securely wiped from memory.
  • Keys: SOPS uses KMS (Key Management Service) providers to manage encryption keys. The most common providers are AWS KMS, GCP KMS, Azure Key Vault, and age. PGP can also be used.
  • Keyring: SOPS maintains a keyring of KMS keys. When encrypting, you specify which keys SOPS should use. When decrypting, SOPS will attempt to use the keys associated with the file.
  • Metadata: SOPS embeds metadata within the encrypted file, including the KMS key IDs used for encryption. This allows SOPS to automatically find the correct keys for decryption.
  • Plaintext vs. Encrypted: SOPS can toggle between encrypted and plaintext versions of a file.

Commands / Usage

Initialization and Configuration

  • Initialize SOPS for a project:

    sops update-age-key secrets.yaml

    This command generates a new age key and embeds it into the secrets.yaml file, making it ready for encryption with age.

  • Add KMS integration (AWS example):

    sops update-kms-key --kms-uri arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab secrets.yaml

    Adds an AWS KMS key ARN to the metadata of secrets.yaml. Replace the ARN with your actual KMS key ARN.

  • Add multiple KMS integrations (GCP example):

    sops update-gcp-kms-key --gcp-key projects/my-gcp-project/locations/global/keyRings/my-keyring/cryptoKeys/my-key secrets.yaml

    Adds a GCP KMS key to the metadata of secrets.yaml.

  • View SOPS configuration:

    sops --config secrets.yaml

    Prints the SOPS configuration embedded in the specified file, showing which KMS keys are configured.

Encryption and Decryption

  • Encrypt a file:

    sops --encrypt --kms-uri arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab secrets.yaml

    Encrypts secrets.yaml using the specified AWS KMS key and replaces the original file content with encrypted data.

  • Encrypt a file with age:

    sops --encrypt --age secrets.yaml

    Encrypts secrets.yaml using the age key associated with the file.

  • Decrypt a file:

    sops --decrypt secrets.yaml

    Decrypts secrets.yaml using the configured KMS keys and prints the plaintext content to standard output.

  • Decrypt a file in-place:

    sops --decrypt --in-place secrets.yaml

    Decrypts secrets.yaml and overwrites the file with its plaintext content.

  • Edit an encrypted file:

    sops --edit secrets.yaml

    Opens secrets.yaml in your default editor, decrypts it, waits for you to save and close, and then re-encrypts it.

  • View specific values from an encrypted file:

    sops --decrypt secrets.yaml | yq '.database.password'

    Decrypts secrets.yaml and pipes the output to yq to extract the database.password value.

  • View all values from an encrypted file:

    sops --decrypt secrets.yaml

    Prints the entire decrypted file content to stdout.

Key Management

  • Rotate KMS keys (AWS example):

    sops --rotate --kms-uri arn:aws:kms:us-east-1:111122223333:key/new-key-abcd-12ab-34cd-56ef-1234567890ab secrets.yaml

    Encrypts the file with a new KMS key while retaining the old ones for backward compatibility.

  • Remove KMS keys (AWS example):

    sops --remove-kms-key arn:aws:kms:us-east-1:111122223333:key/old-key-abcd-12ab-34cd-56ef-1234567890ab secrets.yaml

    Removes a specific KMS key from the file’s metadata. The file must be re-encryptable with the remaining keys.

  • List keys used for encryption:

    sops --list-keys secrets.yaml

    Displays the KMS keys (or age identities) configured for the specified file.

Other Useful Flags

  • --input-type <json|yaml|json5|dotenv|binary>: Specify the input file format.
  • --output-type <json|yaml|json5|dotenv|binary>: Specify the output file format.
  • --format <json|yaml|json5|dotenv|binary>: Alias for --output-type.
  • --string-value <key>: Decrypts only the value for the specified key (useful for shell variables).
  • --unencrypted-suffix .unencrypted: When decrypting in-place, saves the plaintext version with this suffix instead of overwriting.
  • --age: Use age for encryption/decryption.
  • --pgp <fingerprint>: Use PGP with the specified fingerprint.
  • --aws-role <arn>: Assume an IAM role before performing AWS KMS operations.
  • --gcp-service-account <path>: Use a GCP service account file.
  • --azure-kv <vault-name>: Use Azure Key Vault.

Common Patterns

  • Encrypting all secrets in a directory:

    find ./secrets -type f -exec sops --encrypt --kms-uri arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab {} \;

    Finds all files in the ./secrets directory and encrypts them using the specified KMS key.

  • Decrypting all secrets in a directory for a CI/CD job:

    find ./secrets -type f -exec sops --decrypt --in-place {} \;

    Decrypts all SOPS-encrypted files in the ./secrets directory. This is a common step in CI/CD pipelines.

  • Extracting a single secret into an environment variable:

    export DB_PASSWORD=$(sops --decrypt secrets.yaml | yq '.database.password')

    Decrypts the file and uses yq to extract a specific value, assigning it to an environment variable.

  • Using SOPS with helm secrets plugin:

    helm secrets upgrade my-release ./charts/mychart --values secrets.yaml

    The helm-secrets plugin automatically decrypts SOPS files before passing them to Helm.

  • Encrypting a new secret using age: First, ensure secrets.yaml has an age key embedded:

    sops update-age-key secrets.yaml

    Then, add your secret:

    yq -i '.new_api_key = "supersecretkey123"' secrets.yaml

    Finally, encrypt:

    sops --encrypt --age secrets.yaml

  • Decrypting a file for debugging:

    sops --decrypt secrets.yaml > secrets.yaml.decrypted
cat secrets.yaml.decrypted

    Decrypts the file to a temporary file for inspection.

Gotchas

  • Permissions: Ensure the user running sops has the necessary permissions to access the KMS provider (e.g., IAM permissions for AWS KMS, service account credentials for GCP KMS).
  • Key Rotation: If you rotate KMS keys, SOPS will automatically add the new key and retain the old ones. This ensures backward compatibility. However, if you remove an old key and the file still uses it for decryption, you will lose access.
  • File Format: SOPS works best with structured data formats like YAML, JSON, JSON5, and dotenv. While it supports binary files, editing them is less practical.
  • In-place Decryption: Using --in-place is convenient but carries risk. Always ensure you have backups or are in a controlled environment before using it, especially in automated scripts.
  • age vs. KMS: When using age, the public/private key pair is managed directly. For KMS providers, SOPS acts as a client interacting with the cloud provider’s managed keys.
  • Metadata Tampering: If the metadata within the SOPS file (which lists the KMS keys used) is tampered with, SOPS may not be able to decrypt the file.
  • Version Control: Commit encrypted files to Git. Never commit plaintext secrets.
  • CI/CD Decryption: In CI/CD, you’ll typically decrypt secrets at runtime. This often involves injecting cloud credentials or using specific service account permissions for the CI/CD runner.