SOPS: encrypting YAML, JSON, ENV, INI and binary files in place

The problem SOPS solves: secrets that live next to the config they belong to

Most teams keep application configuration in a file that is committed to Git. Somewhere in that file there is an API key, a database password, or a signing key. The usual answers are to keep the whole file out of the repository, to split secrets into a separate store, or to encrypt the entire file so that nobody can read the non-secret parts either.

SOPS takes a fourth route. It is, in the README's words, an editor of encrypted files that supports YAML, JSON, ENV, INI and BINARY formats. It encrypts with AWS KMS, GCP KMS, Azure Key Vault, HuaweiCloud KMS, age, and PGP, and the repository ships example.yaml, example.json, example.ini and example.txt files.

The audience is infrastructure and platform engineers who already treat configuration as code. The repository description calls it a simple and flexible tool for managing secrets, and the README presents it as an editor of encrypted files rather than a secrets server. Whatever reads the file has to decrypt it, either through the sops binary or through a library that understands the format.

How the encryption actually works: a data key wrapped by one or more key services

The repository layout makes the architecture visible. There are separate top-level directories named aes, age, azkv, gcpkms, hckms, hcvault, kms, keys, keyservice, pgp and shamir. Each of those is a key source or a cryptographic primitive, and they are peers rather than layers. The README lists the supported backends explicitly: AWS KMS, GCP KMS, Azure Key Vault, HuaweiCloud KMS, age, and PGP.

The keyservice directory and the shamir directory are the two places where this gets more interesting than a simple wrapper. A keyservice suggests an out-of-process key provider, and shamir indicates threshold splitting, where the data key is reconstructed from a subset of shares. Neither is documented in the README, which points to getsops.io under "Docs" instead, so treat the directory names as a map of what exists rather than as a description of the interface. The hcvault directory, combined with the HashiCorp Vault API dependency in go.mod, shows that Vault is supported as a key source even though the README's backend list does not name it.

The dependency list is a fair picture of the operational surface. The AWS SDK v2 modules for KMS, S3, STS and credentials appear alongside the Azure azidentity and azkeys packages, the Google Cloud KMS and storage packages, the HuaweiCloud SDK, filippo.io/age, and ProtonMail/go-crypto for PGP. Adopting SOPS means accepting whichever of those credential chains you actually use.

Installing SOPS and encrypting a first YAML file

The repository's Makefile exposes an install target that builds the CLI from source with the Go toolchain:

make install

That target runs go install on github.com/getsops/sops/v3/cmd/sops, so the binary lands in your Go bin directory. The Makefile pins GOPROXY to https://proxy.golang.org for that build. The README itself does not give install instructions; it points to getsops.io under "Docs", and the repository ships a .goreleaser.yaml, which is the usual sign that prebuilt release binaries exist.

Once the binary is on your PATH, the first real use is a configuration file that tells SOPS which key to use for which path. The repository keeps a .sops.yaml at its root, and the config directory holds the parsing logic for it. The repository also ships examples/all_in_one/ and examples/per_file/, which are the directories to read before writing your own rules. The README does not print the schema of that file; the docs site at getsops.io is where it is described.

With the configuration in place, the workflow is a round trip. Run sops on a file and it opens in your editor with the values decrypted and re-encrypts them on save. That round trip is what the tool is built around, and it is why the encrypted file stays in the repository rather than being generated at deploy time. The README does not list the individual command-line flags for encrypting or decrypting, so read the docs site before scripting either operation.

Where SOPS stops: rotation, key loss and the metadata error

One limitation is key rotation. The README does not document rollback, and it does not describe a rotation procedure; check the docs at getsops.io before relying on a specific rotation or re-encryption scheme.

The third is that SOPS is the wrong tool when the secret needs to reach a process that has no file and no credential chain. A container that starts with a read-only filesystem and no cloud identity cannot decrypt anything. SOPS assumes the consumer either has the sops binary and credentials, or links a library that does. Teams that want a runtime API returning a secret over HTTP are looking at a different category of tool, and SOPS will not grow into one.

SOPS compared with HashiCorp Vault: file transformer versus secret server

The natural alternative is HashiCorp Vault, and the difference is architectural rather than a matter of feature lists. Vault is a server. It stores secrets, enforces policy on who may read which path, issues short-lived credentials, and keeps an audit log of every access. Applications authenticate to it and fetch what they need at runtime.

SOPS is a client-side file transformer. Access control is delegated entirely to the key service: whoever can call AWS KMS Decrypt on the right key, or holds the age private key, can decrypt the file. That is a strength when your access control already lives in IAM or in a key file, and a gap when you need per-secret policy.

The two are not mutually exclusive, and the repository hints at that. The hcvault directory and the hashicorp/vault/api dependency in go.mod mean Vault can serve as a key source for SOPS, so a team can keep the encrypted file in Git while the data key is wrapped by Vault. That is a middle path: the file is reviewable, and unwrapping the data key goes through Vault's policy and audit machinery. The README does not describe this configuration, so it has to be learned from the docs site rather than from the repository front page.

Maintenance, release cadence and what MPL-2.0 means for adopters

The repository is not archived, and the last push was on 2026-11-02. The most recent release listed is v3.13.3 on 2026-07-23, preceded by v3.13.2 on 2026-06-30 and v3.13.1 on 2026-05-16. That is three patch releases in a little over two months, with no major version bump in the list.

The project's governance is worth noting because it affects upgrade risk. The README states that SOPS was initially launched as a project at Mozilla in 2015 and was donated to the CNCF as a Sandbox project in 2023, now under a separate group of maintainers. Sandbox is the earliest CNCF maturity stage, and the README does not describe a graduated roadmap. For an adopter, that means the project is not abandoned, but it also means the maintainer group is the thing to check rather than an assumed corporate backer.

Upgrade cost is mostly a Go module question. The go.mod declares go 1.25.8 and pulls cloud SDKs at specific versions, so anyone building from source inherits those pins. The Makefile's default target runs test, vet, generate, install and functional-tests, and there is a separate origin-build target that adds functional-tests-all, which suggests the full functional suite is heavier than the default. If you vendor the binary rather than the library, upgrades are a binary swap plus a re-read of the CHANGELOG.md at the repository root.

The licence is MPL-2.0, a file-level copyleft licence. Modifying SOPS source files obliges you to publish those modified files under the same licence; using the binary alongside your own proprietary code does not. That is a summary of the licence identifier, not legal advice, and the LICENSE file at the repository root is the authoritative text.

Editorial conclusion

SOPS fits teams that already store configuration in Git and want encrypted secrets to stay in Git alongside the rest of their configuration. It is the wrong tool if you need a server that hands out secrets at runtime, or if your configuration is not file-shaped at all. Before adopting it, verify which key service you can actually authenticate against, check that your .sops.yaml configuration matches the paths you will encrypt, and confirm the MPL-2.0 licence is acceptable to your legal reviewers.

Frequently asked questions

Official sources

1. getsops/sops on GitHub
2. License: MPL-2.0
3. Project website
4. README
5. Releases