Skip to content

SOPS

SOPS ⧉ (short for Secret OPerationS) is a tool for reading and writing files containing encrypted values. It supports several mechanisms for encryption; Currently we use GPG which means that you have to add your GPG public key to the monorepo if you want to use SOPS.

SOPS files are simply YAML files that potentially contain both encrypted and unencrypted values as well as some SOPS metadata. For simplicity, all of our SOPS files solely contain key-value pairs (no lists, dictionaries etc.).

Installation

We manage SOPS via Mise, i.e. you can install it via mise install after setting up Mise.

Adding Users

In order to let a new team member access SOPS files, they need to add their GPG public key to the monorepo. The key's fingerprint then needs to be added to .sops.yaml.

Afterwards, all SOPS files need to be re-encrypted with sops updatekeys <file>. This requires first importing all users' GPG keys. Re-encryption can be accomplished as follows:

find infra/inventory -type f \
  | grep -E 'infra/inventory/.*/(account_passwords|config)\.yml$' \
  | while read -r f; do
      sops updatekeys -y "$f"
    done

Editing Files

You can simply open and edit SOPS files via:

sops <some-file>

Use the EDITOR environment variable to control which text editor to use. The file will be displayed in your editor with all values shown in plaintext. After writing and closing the files, secret values will automatically be re-encrypted.

To control which values are secrets and which are non-secrets, we append the _SECRET postfix to keys with secret values. This postfix is stripped by tooling interacting with SOPS files, i.e. a key MY_SECRET_SECRET would in fact represent a MY_SECRET variable with a secret value.

SOPS knows that it has to encrypt these keys because of the encrypted_regex setting in .sops.yaml.

We use a custom merge driver (scripts/sops-merge-driver) to avoid merge conflicts due to automatically updated lastmodified and mac values in the SOPS metadata of each file. Git should automatically pick this up and save you from any merge-related woes when editing sops files concurrently with someone else. You will of course still encounter merge conflicts when e.g. someone else has modified the same key.