Core concepts

GitVaulty combines Git's reviewable history with SOPS and age encryption. The repository contains everything required to decide who should have access, but never contains a private decryption key.

Encrypted files

A logical file such as .env is stored as .env.gitvaulty. The ciphertext protects the entire file: names inside it, values, comments, formatting, and file type are not visible. Git still tracks the encrypted file as an ordinary repository artifact.

Commands always accept the logical plaintext path. For example, edit config/secrets.yaml rather than config/secrets.yaml.gitvaulty:

npx gitvaulty edit config/secrets.yaml

One identity per person

Every person keeps one private GitVaulty master identity on their own machines. Its public age recipient and verification key can be registered in a repository, but the private backup must never be shared or committed.

npx gitvaulty key public
npx gitvaulty key backup

Because there is no shared team decryption key, removing a person and re-encrypting affected files does not require distributing a replacement secret to everyone else.

Public registry and signed groups

.gitvaulty/recipients.json is the public identity and access registry. Groups assign reusable access policies to files; the initial default group is team. Group-policy changes are signed by a current manager, which makes access changes reviewable in Git and verifiable by the CLI.

Direct user grants are available for exceptions, but groups are the normal way to express team access. A file can belong to multiple groups and can also grant selected users direct access.

Plaintext boundaries

GitVaulty avoids persistent plaintext by default. edit uses a private temporary directory, cat streams bytes, and run exposes selected files only for the lifetime of a child command. materialize is the explicit option when normal development tools need files on disk; clean removes unchanged materialized copies afterward.

Choose the narrowest workflow that fits the tool you are running, and never place secret values in prompts, command arguments, logs, or commits.