SOPS: English for GitOps Secret Management Engineers

SOPS (Secrets OPerationS) solves one of the most persistent problems in GitOps: how to store encrypted secrets safely in a version-controlled repository without exposing plaintext values. Engineers working with Kubernetes, Helm, and ArgoCD need to speak confidently about encryption key types, creation rules, and plugin integrations in pull request reviews, runbooks, and on-call handoffs. This guide covers the English vocabulary that is essential for working with SOPS professionally.

Key Vocabulary

SOPS — a Mozilla-developed open-source tool that encrypts specific values (not the entire file) within YAML, JSON, ENV, and INI files, leaving keys and structure visible while protecting secret values. “We commit all our Kubernetes secrets to Git as SOPS-encrypted YAML — the key names are visible for auditing, but the values are ciphertext that only authorised keys can decrypt.”

age — a modern, simple file encryption tool that is the recommended key type for new SOPS implementations; it uses X25519 key exchange and is designed to replace PGP for most use cases. “We migrated from PGP to age keys last quarter — the recipients list in .sops.yaml is much shorter and there’s no keyring to manage on developer laptops.”

PGP (Pretty Good Privacy) — the older, more complex encryption standard that SOPS also supports; still common in organisations that already have a PGP key infrastructure or use GPG for code signing. “The legacy secrets are still encrypted with the team’s PGP fingerprints, but all new secrets use age so we can retire the GPG keyring once the migration is complete.”

.sops.yaml — the configuration file placed at the root of a repository that defines creation rules, telling SOPS which key(s) to use when encrypting a file based on its path or filename pattern. “I added a new creation rule to .sops.yaml so that any file matching clusters/prod/**/*.yaml is automatically encrypted with both the production age key and the AWS KMS key.”

Creation rule — an entry in .sops.yaml that matches files by path glob and specifies the encryption keys (age recipients, PGP fingerprints, AWS KMS ARNs, GCP KMS resource IDs, or Azure Key Vault URIs) that SOPS uses when creating or re-encrypting a matched file. “Without a matching creation rule, running sops --encrypt on a new file will fail — you need to specify at least one recipient in the rule before SOPS knows which public key to use.”

Encrypt / decrypt — the two core operations: sops --encrypt transforms a plaintext file into a SOPS-encrypted file; sops --decrypt reverses the operation for use in a deployment pipeline. “The CI job decrypts the secrets file with sops --decrypt and pipes the output directly into kubectl apply — the plaintext never touches the filesystem.”

ArgoCD SOPS plugin — a mechanism (implemented either as a custom Config Management Plugin or via the argocd-vault-plugin) that allows ArgoCD to automatically decrypt SOPS-encrypted secrets during the sync process, injecting plaintext values into the cluster without manual intervention. “Once we installed the SOPS plugin in the ArgoCD repo-server container, encrypted secrets in Git are transparently decrypted at sync time — no engineer needs to manually decrypt anything during a deployment.”

Key rotation — the process of re-encrypting SOPS-managed secrets with a new key, typically triggered when a team member leaves, a key is compromised, or as part of a scheduled security policy. “After the contractor’s access was removed, we ran sops updatekeys on every encrypted file in the repository to rotate out their age public key from all creation rules.”

Useful Phrases

• “I’ve added your age public key to the creation_rules block in .sops.yaml — pull the latest and you should be able to decrypt the staging secrets.”
• “Never commit a plaintext secret to Git even temporarily; encrypt it first with sops --encrypt and verify the output before staging the file.”
• “The creation rule uses a path_regex to match all files under env/production/ and specifies three age recipients — the platform team key, the CI key, and the KMS key for the automated pipeline.”
• “We keep the .sops.yaml at the repo root so that every developer’s SOPS installation picks it up automatically without needing extra flags on the command line.”
• “To rotate keys, update the recipients in .sops.yaml first, then run sops updatekeys on each encrypted file — the re-encryption uses the new recipient list while preserving the underlying plaintext.”

Common Mistakes

Saying “SOPS encrypts the whole file”. SOPS is specifically designed to encrypt values, not entire files. The YAML structure, keys, and comments remain as readable plaintext. Non-native speakers sometimes describe SOPS as “encrypting the secret file,” which implies the entire file is opaque ciphertext. The accurate phrasing is “SOPS encrypts the values in the file” or “the secret values are encrypted; the keys are visible.” This distinction matters because it is what makes SOPS-encrypted files safe to diff and audit in pull requests.

Confusing “recipient” and “key”. In SOPS and age terminology, a recipient is the public key to which a file is encrypted — the entity that will be able to decrypt it. An age key or key pair refers to both the public and private components. Engineers sometimes say “add your key to the SOPS config” when they should say “add your public key as a recipient.” In a security context, being precise about public versus private keys is important and signals trustworthiness to native-speaking colleagues.

Using “decode” instead of “decrypt”. In English engineering vocabulary, decode typically means reversing an encoding scheme (base64, URL encoding) that has no cryptographic secrecy — anyone can decode base64. Decrypt means reversing a cryptographic operation that requires possession of a private key. SOPS files are decrypted, not decoded. Saying “I’ll decode the secret” in a SOPS context sounds like you are treating encryption as mere obfuscation, which undervalues the security model.

Communicating accurately about SOPS in English builds trust with your team and signals that you understand the security model, not just the tool — both matter when secrets are at stake.