Encrypt secrets in Git with SOPS and age

Keep encrypted secrets safely in your repo, decrypt them in CI, and never commit a plaintext credential again.

A GitOps repository wants every input in Git, and a database password is an input. The two bad answers are committing it in plaintext and keeping it somewhere the reconciler cannot see. SOPS is the third answer for the static, low-volume secrets that belong with the manifests: it encrypts the values of a YAML, JSON, ENV or INI file and leaves the keys readable, so git diff still shows that db_password changed and code review still works. Paired with age, a small X25519-based encryption tool, there is no KMS bill and no key server, only a public key in the repo and a private key wherever decryption happens.

The mechanism is worth understanding before the commands, because it explains the one operational rule people get wrong: SOPS generates a random data key per file, encrypts each matched value with it, and then stores that data key once per recipient, wrapped with the recipient's public key, in a plaintext sops: block at the bottom of the same file.

Keys: one identity per decrypting party

Every person and every CI job that decrypts gets its own age identity. age-keygen writes a file containing both halves; the line starting # public key: age1… goes into .sops.yaml, the AGE-SECRET-KEY-… line goes into a password manager or a CI secret store and nowhere near the repository. SOPS looks for identities in SOPS_AGE_KEY (the key text), SOPS_AGE_KEY_FILE (a path), SOPS_AGE_KEY_CMD (a command that prints keys), and otherwise in keys.txt under the user config directory: ~/.config/sops/age/keys.txt on Linux, ~/Library/Application Support/sops/age/keys.txt on macOS. SSH ed25519 and RSA public keys are also accepted as recipients, which is a reasonable shortcut for a team that already manages SSH keys.

.sops.yaml: which paths encrypt to which recipients

Creation rules map a path pattern to a recipient list, so platform engineers can decrypt secrets/infra/ while an application team decrypts only secrets/apps/shop/, with no wrapper scripts. encrypted_regex limits encryption to the keys that hold secret material; leaving apiVersion, kind and metadata readable is what keeps a Kubernetes Secret manifest reviewable and lets tooling that inspects manifests keep working.

creation_rules:
  - path_regex: secrets/infra/.*\.yaml$
    encrypted_regex: '^(data|stringData)$'
    age: >-
      age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p,
      age1<ci-job-public-key>
  - path_regex: secrets/apps/shop/.*\.yaml$
    encrypted_regex: '^(data|stringData)$'
    age: age1<shop-team-public-key>

Encrypt in place, then read the diff

sops encrypt -i rewrites the file in place using the rule that matches its path; sops edit opens the decrypted content in $EDITOR and re-encrypts on save. After encryption every matched value is an ENC[AES256_GCM,data:…,iv:…,tag:…,type:str] token and the keys are untouched, which is exactly what a reviewer needs: they can see that db_password was rotated without seeing either password.

The order matters more than any flag: encrypt before the first commit. Deleting a plaintext secret in the next commit does not remove it from clones, forks, CI caches or backups, and at that point rotation of the credential is the only honest fix. A gitleaks pre-commit hook turns that rule into something a fat-fingered git add . cannot break.

Adding and removing recipients

Adding a teammate is two commands: put their public key in .sops.yaml, then run sops updatekeys on each affected file so the existing data key is wrapped for the new recipient as well; the run confirmed that the ciphertext of every value is byte-identical before and after, which is what "same data key, one more wrap" means. Removing someone is where the envelope model bites. sops updatekeys after deleting their key rewrites the wrapped-key list and does lock them out of the file as it now stands, but the data key is still the same one, and it is inside every commit they could previously decrypt, which their private key still unwraps: in the run, the previous commit opened with the removed key after updatekeys and after rotate alike. sops rotate -i generates a new data key and re-encrypts the values, and only that changes what the current version is encrypted with; sops rotate -i --rm-age <key> does the removal and the rotation in one step. History stays readable to them regardless; if that matters, the secrets themselves are rotated too.

Decrypting where the deploy happens

In a pipeline the private key arrives through the CI secret store as SOPS_AGE_KEY, and the decrypted output is piped straight into the tool that needs it, so no plaintext file is written to the runner. For Flux and Argo CD the better shape is to give the controller the identity and let it decrypt at reconcile time, so developer laptops never need the production key at all; Flux's kustomize-controller reads it from a Secret referenced by the Kustomization's decryption block. Either way the plaintext exists only in memory and in the target system, never in the repository.

deploy:
  variables:
    SOPS_AGE_KEY: $AGE_PRIVATE_KEY     # masked CI variable, never in the repo
  script:
    # decrypt straight into kubectl: no plaintext file on the runner's disk
    - sops decrypt secrets/infra/database.yaml | kubectl apply -f -

When a change locks people out: recovery in order of preference

SOPS answers the storage question and stops there. It cannot tell you who decrypted a file last week, it does not expire anything, and it cannot hand a job a database credential that dies in ten minutes. Those are the reasons a team eventually moves the source of truth to Vault and syncs into the cluster with External Secrets, keeping SOPS for the bootstrap secrets that have to exist before Vault does. Until then, the two habits that matter are the ones above: encrypt before the first commit, and rotate when someone leaves.

Related posts

Quick reference