README
¶
EnvGuardian
Commit your team's .env to git — encrypted — so cloning or pulling the repo
is all it takes to have working local configuration.
EnvGuardian is a key-management and git-integration layer over
age. It encrypts your .env to every
developer's public key and commits the ciphertext. Access is a plaintext,
reviewable recipients file: adding a teammate is a pull request.
Status: early development (M2). Working commands:
init,encrypt,decrypt,add-recipient,list-recipients,check,install-hooks,diff.
Quick start
envguardian init # scaffold config, seed you as a recipient, fix .gitignore
# create your .env, then:
envguardian encrypt # writes .env.age (idempotent — no diff churn)
envguardian install-hooks # auto-decrypt after pull; block plaintext commits
git add .env.age .envguardian && git commit -m "add encrypted config"
A teammate clones the repo and runs envguardian decrypt — using an SSH key
they already have. To grant access: envguardian add-recipient --github <user>,
then commit the updated recipients.toml and .env.age.
CI: verifying sync
envguardian check verifies the repo is in sync and exits non-zero if not:
the ciphertext matches the plaintext (when decryptable), the recipients file is
well-formed, the recipient-set fingerprint in lock.toml matches
recipients.toml, plaintext files are gitignored, no rotations are pending, and
the config version is supported. It reports every failure, not just the
first, and supports --json.
Store a CI identity's private key as a repository secret (e.g. AGE_KEY),
then:
# .github/workflows/envguardian.yml
name: envguardian
on: [push, pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: "1.24"
- run: go install github.com/YehiaGewily/envguardian/cmd/envguardian@latest
- name: Verify secrets are in sync
env:
ENVGUARDIAN_IDENTITY: ${{ secrets.AGE_KEY }}
run: envguardian check
$ENVGUARDIAN_IDENTITY accepts either a path or the raw key material, so the
secret can be passed inline as above. Add the CI key as a recipient with
envguardian add-recipient --key age1... --name ci so check can decrypt.
Non-goals
| Not this | Use instead |
|---|---|
| A runtime secrets manager | Vault, AWS Secrets Manager |
| Production secret injection | Your cloud provider's parameter store |
| A server / SaaS | There is no server. That's the point. |
| Storage for large or binary secrets | Object storage with its own encryption |
| A compliance or audit system | Real IAM with real audit logs |
Build
make build
./envguardian version
Requires Go 1.24+.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
envguardian
command
Command envguardian is the CLI entry point for EnvGuardian.
|
Command envguardian is the CLI entry point for EnvGuardian. |
|
internal
|
|
|
atomic
Package atomic writes files atomically: content is written to a temp file in the same directory, fsync'd, and renamed over the destination, so a reader (or a crash) never observes a half-written file.
|
Package atomic writes files atomically: content is written to a temp file in the same directory, fsync'd, and renamed over the destination, so a reader (or a crash) never observes a half-written file. |
|
cli
Package cli wires up the cobra command tree for EnvGuardian.
|
Package cli wires up the cobra command tree for EnvGuardian. |
|
config
Package config reads and writes .envguardian/config.toml, which maps each plaintext file to its committed ciphertext, and resolves the conventional paths of the .envguardian directory.
|
Package config reads and writes .envguardian/config.toml, which maps each plaintext file to its committed ciphertext, and resolves the conventional paths of the .envguardian directory. |
|
crypt
Package crypt is a thin wrapper over filippo.io/age.
|
Package crypt is a thin wrapper over filippo.io/age. |
|
dotenv
Package dotenv parses and writes .env files while preserving comments, blank lines, and key order.
|
Package dotenv parses and writes .env files while preserving comments, blank lines, and key order. |
|
gitint
Package gitint handles git integration: the post-merge, post-checkout, and pre-commit hooks, the .gitignore guard, and the diff/merge drivers for encrypted files.
|
Package gitint handles git integration: the post-merge, post-checkout, and pre-commit hooks, the .gitignore guard, and the diff/merge drivers for encrypted files. |
|
keys
Package keys loads and saves the recipients file and resolves the local decryption identity.
|
Package keys loads and saves the recipients file and resolves the local decryption identity. |
|
rotation
Package rotation manages the rotation ledger: the pending-rotation entries opened when a recipient is revoked and closed once the underlying credential has been reissued at its source system.
|
Package rotation manages the rotation ledger: the pending-rotation entries opened when a recipient is revoked and closed once the underlying credential has been reissued at its source system. |