Git Seal

Git Seal is a Git-native encrypted environment manager for repositories and local teams.

It stores environment structure in Git, encrypts explicit values per environment, and exposes a local CLI plus terminal UI for editing and runtime execution.

Install

Install it into the repository that should own the .git-seal/ data:

npm install --save-dev git-seal
npx git-seal init

If you prefer a global install:

npm install --global git-seal
git-seal init

Common workflow

Initialize the repository metadata:

git-seal init

Create identities and environments:

git-seal identity create alice
git-seal identity create ci-production --storage token
git-seal env create base
git-seal env create development --parent base
git-seal env create production --parent base
git-seal env add-member base alice
git-seal env add-member production ci-production

Set and inspect encrypted values:

git-seal value set --env base API.PG.HOST db.internal
git-seal value set --env production API.PG.PASSWORD
git-seal value set --env production DATABASE.URL 'postgres://{{ API.PG.USER }}:{{ API.PG.PASSWORD }}@{{ API.PG.HOST }}/app'
git-seal value get --env production DATABASE.URL
git-seal value list --resolve
git-seal value list --env production --resolve --reveal
git-seal value clear --env production API.PG.PASSWORD

Inspect and refactor key paths:

git-seal key list
git-seal key rename API.PG.HOST DATABASE.PG.HOST
git-seal key remove DATABASE.PG.HOST

Keep encrypted recipient state aligned with environment membership:

git-seal status
git-seal sync

Migrating repositories from values format 2

After upgrading to a release that uses values format 3, migrate an existing repository once:

git-seal migrate

The command migrates the whole repository and requires access through an authorized locally installed identity for each environment that has active encrypted values. Different environments may use different local identities. Run the migration before making other changes to .git-seal/values.json, then commit the migration as a standalone change before other branches continue editing encrypted values. The migration creates fresh encrypted cells, so an ordinary line-by-line diff is not meaningful.

Repositories already on format 3 are left unchanged. Migration removes format-2 plaintext hashes from the current tree, but it does not rewrite Git history; old commits retain their historical metadata and ciphertext.

Run a process with resolved runtime variables:

git-seal exec --env production -- node server.js

Runtime environment selection is always explicit. Pass --env or set GIT_SEAL_ENV; NODE_ENV is an application variable and does not select a Git Seal environment. For example, automation may use:

GIT_SEAL_ENV=production git-seal exec -- node server.js

Open the interactive terminal UI:

git-seal ui

Repository format

Git Seal initializes a .git-seal/ directory with a small set of structured files:

• .git-seal/config.json: repository metadata such as identities, environments, inheritance, and declared keys.
• .git-seal/values.json: encrypted explicit values and recipient metadata.
• .git-seal/local-config.json: machine-local identity installation state. This file is ignored from Git.
• .git-seal/keys/: machine-local key material for file-backed identities. This directory is ignored from Git.
• .git-seal/cache/: local cache data. This directory is ignored from Git.

The repository structure stays readable in Git diffs. Plaintext secret values do not.

See SECURITY.md for the threat model, exposure boundaries, historical-access limitations, and private vulnerability-reporting channel.

Keychain-backed identities store private material in the machine Keychain under the pathless service name git-seal:<identity-name>, with the Keychain account set to the identity name. This intentionally makes keychain-backed identity names machine-global: two repositories that use the same identity name refer to the same local Keychain item.

Commands

Top-level commands:

• git-seal init
• git-seal migrate
• git-seal identity create <name>
• git-seal identity list
• git-seal env create <name> [--parent <parent>]
• git-seal env add-member <env> <identity>
• git-seal env remove-member <env> <identity>
• git-seal env set-parent <env> [parent]
• git-seal env list
• git-seal key list
• git-seal key rename <from> <to>
• git-seal key remove <path>
• git-seal value set --env <env> <key> [value]
• git-seal value get --env <env> <key>
• git-seal value clear --env <env> <key>
• git-seal value list [--env <env>] [--resolve] [--reveal]
• git-seal status
• git-seal sync
• git-seal exec --env <env> -- <command...>
• git-seal health
• git-seal merge
• git-seal ui