aheissenberger/gitvault

# gitvault 面向多开发者和 AI-agent 工作流的 Git 原生密钥管理器。密钥通过 [age](https://age-encryption.org) 加密并存储在你的代码仓库中 — 永远不以明文存储，无需 外部服务。

 

## 功能特性 | 类别 | 亮点 | |---|---| | **加密** | age 标准格式；支持全文件或逐字段 (JSON/YAML/TOML)；流式加密；明文归零处理 | | **多接收者** | 一次加密，所有团队成员均可解密；每人对应独立的 `.pub` 文件；最多支持 256 个接收者 | | **确定性差异** | 未更改的字段值保留原有密文 → 最大程度减少 git 噪音 | | **环境管理** | `GITVAULT_ENV` → `.git/gitvault/env` → `dev`；支持 per-worktree 解析 | | **入职引导** | `gitvault init` 一条命令完成身份 → 接收者 → 加固的全流程引导 | | **接收者流程** | 基于 PR 的零共享密钥入职；`identity pubkey`, `recipient add-self` | | **密钥重置** | `rekey` 将所有密钥重新加密给当前接收者列表；支持 `--dry-run` | | **原地编辑** | `seal`/`unseal` 用于字段级原地加密；`edit` 在编辑器中打开已密封或存储文件并在保存时重新密封；`get`/`set` 以编程方式读取或更新单个键值 | | **运行时注入** | `run` 将密钥注入子进程环境变量；不写入 `.env` 文件 | | **生产环境屏障** | HMAC-SHA256 认证的定时准入令牌；`revoke-prod` 立即清除 | | **身份来源** | `--identity-stdin` → `--identity` → `GITVAULT_IDENTITY_FD` → `GITVAULT_IDENTITY` → OS keyring → SSH agent | | **OS keyring** | macOS Keychain, Linux Secret Service, Windows Credential Manager | | **Git 安全** | pre-commit/pre-push hooks；漂移检测；已提交历史泄露扫描；merge driver | | **CI 友好** | `--json`, `--no-prompt`；`CI=1` 自动启用非交互模式；稳定的退出代码 | | **AWS SSM** | `gitvault ssm pull/push/diff/set`; `--features ssm` | ## 安装 ``` # macOS brew install aheissenberger/tools/gitvault # 从源代码构建 cargo build --release ``` ### 预编译二进制文件 从 [GitHub Releases](https://github.com/aheissenberger/gitvault/releases) 下载最新版本： - `gitvault-linux-x86_64.tar.gz` - `gitvault-macos-aarch64.tar.gz` - `gitvault-windows-x86_64.zip` 每个版本均包含 SHA256SUMS 和 cosign `.sig`/`.pem` 文件以供验证。 ## 快速开始 ### 1. 设置新仓库 ``` gitvault init # one command: identity → add-self → harden → config.toml ``` 然后使用 `harden` 导入任何现有的明文密钥文件： ``` gitvault harden .env --env dev # encrypts .env, git rm --cached, gitignores it gitvault harden config/secrets.json --env dev # same for any other file ``` 最后，提交你的加密文件和公钥，然后添加你的团队成员： ``` git add .gitvault/ git commit -m "secrets: initial encrypted vault" git push ``` → 完整的添加团队成员工作流请参阅 [docs/recipient-management.md](docs/recipient-management.md)。 ### 2. 加入现有仓库（新团队成员） ``` gitvault init # creates identity, adds your public key to .gitvault/recipients/ # 使用您的公钥开启 PR： git add .gitvault/recipients/ && git commit -m "onboard: add " git push && gh pr create ``` 在维护者合并并重置密钥后：`git pull && gitvault materialize` → 维护者重置密钥的步骤请参阅 [docs/recipient-management.md](docs/recipient-management.md)。 ### 3. CI/CD ``` # 推荐：使用 GITVAULT_IDENTITY_FD 以避免密钥出现在 /proc//environ 中 # （仅限 Linux/macOS；FD 不是 secret — 只有 FD 内容是敏感的） GITVAULT_IDENTITY_FD=3 gitvault materialize --no-prompt --env prod 3<<<"$SECRET_KEY" # 备选：GITVAULT_IDENTITY（密钥路径或原始 AGE-SECRET-KEY- 字符串） GITVAULT_IDENTITY="$SECRET_KEY" gitvault materialize --no-prompt --env prod # 或者直接注入而不写入 .env： GITVAULT_IDENTITY="$SECRET_KEY" gitvault run --no-prompt -- node server.js ``` ## CLI 参考 ``` gitvault [OPTIONS] Global options: --json --no-prompt --identity-stdin --identity-selector (--aws-profile --aws-role-arn only with --features ssm) Commands: init Onboard a new team member (identity, recipient, repo hardening) harden Harden repo (hooks, .gitignore); or import+encrypt a file with harden encrypt Encrypt a file into .gitvault/store// using mirrored source path decrypt Decrypt from .gitvault/store// using source path or explicit .age path (--reveal) materialize Materialize secrets to root .env status Check repository safety status run Inject secrets into child process env (--clear-env, --keep-vars) allow-prod Write a timed production allow token revoke-prod Revoke the production allow token immediately recipient Manage recipients: add | remove | list | add-self rekey Re-encrypt all secrets for current recipients (--dry-run, --env, --json) keyring Manage identity key in OS keyring: set | get | delete | set-passphrase | get-passphrase | delete-passphrase identity Manage identities: create [--add-recipient] | pubkey check Preflight validation without side effects (-H / --skip-history-check) ai Print embedded skill or context file for AI agents: ai skill | ai context seal In-place field/value encryption for JSON/YAML/TOML/.env unseal In-place field/value decryption for JSON/YAML/TOML/.env (--reveal) edit Open sealed or encrypted file in editor; re-seal/re-encrypt on save get Read a single key's plaintext value from a sealed or encrypted file set Update (or create) a single key's value in a sealed or encrypted file ssm AWS SSM Parameter Store sync (--features ssm) ``` ### 操作员快速映射表 | 任务 | 命令 | |------|---------| | 入职新团队成员 | `gitvault init` | | 导入并加密现有文件 | `gitvault harden --env ` | | 加密整个文件 | `gitvault encrypt --env ` | | 原地密封选定字段 | `gitvault seal --fields a.b,c` | | 原地密封 `.env` 值 | `gitvault seal .env` | | 编辑已密封文件 | `gitvault edit ` | | 编辑 store-encrypted 文件 | `gitvault edit ` | | 读取单个键值 | `gitvault get ` | | 更新单个键值 | `gitvault set ` | | 更新键（密钥输入，无历史记录） | `echo val \| gitvault set --stdin` | | 解密到 stdout | `gitvault decrypt --reveal` | | 解封到 stdout | `gitvault unseal --reveal` | | 物化根 `.env` | `gitvault materialize` | | 运行注入密钥的命令 | `gitvault run --keep-vars -- [args...]` | | 安全检查（CI 友好） | `gitvault status --fail-if-dirty --no-prompt` | | 验证设置（无副作用） | `gitvault check [-H] [--env ]` | | 启用生产操作窗口 | `gitvault allow-prod [--ttl ]` | | 撤销生产窗口 | `gitvault revoke-prod` | | 管理接收者 | `gitvault recipient add\|remove\|list\|add-self` | | 成员变更后重新加密 | `gitvault rekey [--dry-run] [--env ]` | | 创建身份 | `gitvault identity create [--profile classic\|hybrid] [--add-recipient]` | | 打印自己的公钥 | `gitvault identity pubkey` | | OS keyring | `gitvault keyring set\|get\|delete` | | SSH 身份密码 | `gitvault keyring set-passphrase\|get-passphrase\|delete-passphrase` | | AI 技能 / agent 上下文 | `gitvault ai skill` / `gitvault ai context` | | 打印命令帮助 | `gitvault --help` | ## 配置 优先级（从高到低）：CLI 标志 → `GITVAULT_*` 环境变量 → `.gitvault/config.toml` → `~/.config/gitvault/config.toml` → 内置默认值。 两个可选的 TOML 配置文件 — 缺失的文件会被静默忽略： | 文件 | 范围 | |------|-------| | `.gitvault/config.toml` | 仓库级（随项目提交） | | `~/.config/gitvault/config.toml` | 用户全局个人默认设置 | → 完整配置参考、所有 `GITVAULT_*` 环境变量和 TOML 示例：[docs/reference.md § Configuration](docs/reference.md#configuration-files) ## 退出代码 | 代码 | 含义 | |------|---------| | `0` | 成功 | | `1` | 常规错误 (I/O, 加密失败) | | `2` | 用法 / 参数错误 | | `3` | 在跟踪文件或已提交历史中检测到明文密钥 | | `4` | 解密错误（密钥错误、文件损坏） | | `5` | 未满足生产环境屏障要求 | | `6` | 检测到密钥漂移（加密文件有未提交的更改） | ## 仓库布局 ``` / ├── .gitvault/ │ ├── store// # encrypted artifacts (commit these) │ │ └── app.env.age │ ├── recipients/ # one .pub file per recipient (commit these) │ │ ├── alice.pub │ │ └── bob.pub │ ├── plain// # decrypted plaintext (gitignored) │ └── config.toml # optional repo-level config ├── .git/gitvault/ │ ├── env # active environment name (optional, gitignored) │ └── .prod-token # timed production allow-token (gitignored) ├── .env # materialized root env (gitignored) ├── .gitattributes # optional: register merge driver for .env └── .gitignore # managed by `gitvault harden` ``` ## 身份解析 优先顺序（从高到低）：`--identity-stdin` → `--identity` / `GITVAULT_IDENTITY_FD` → `GITVAULT_IDENTITY` → OS keyring → SSH agent。 → 每种身份方法的设置说明：[docs/identity-setup.md](docs/identity-setup.md) → 完整的优先级表和安全说明：[docs/reference.md § Identity Resolution](docs/reference.md#identity-resolution) ## 文档 **操作指南** — 面向任务的演练： | 指南 | 描述 | |-------|-------------| | [docs/identity-setup.md](docs/identity-setup.md) | 设置你的身份密钥 (keyring, age 文件, SSH, 基于 FD) | | [docs/recipient-management.md](docs/recipient-management.md) | 添加/移除团队成员，PR 流程，rekey 工作流 | | [docs/cicd-recipes.md](docs/cicd-recipes.md) | GitHub Actions, Docker, Kubernetes 配方 | | [docs/secret-formats.md](docs/secret-formats.md) | 加密 .env, JSON, YAML, TOML 文件 | **参考** — 完整的技术规范： | 参考 | 描述 | |-----------|-------------| | [docs/reference.md](docs/reference.md) | 完整 CLI 参考：所有命令、标志、环境变量、配置、退出代码 | | [docs/ai/skill.md](docs/ai/skill.md) | AI agent 技能参考（内嵌于二进制文件中） | **开发者文档：** | 文档 | 描述 | |-----|-------------| | [docs/development.md](docs/development.md) | 构建、测试和开发工作流 | | [docs/releasing.md](docs/releasing.md) | 维护者发布手册 | | [docs/ai/AGENT_START.md](docs/ai/AGENT_START.md) | AI agent 入职和架构 | ## 替代方案 | 工具 | 方法 | |------|----------| | [SOPS](https://github.com/getsops/sops) | 结构化文件加密 (YAML/JSON/.env)；非常适合 KMS 支持的工作流 | | [git-crypt](https://github.com/AGWA/git-crypt) | 通过 Git 过滤器进行透明的全文件加密 | | [git-secret](https://github.com/sobolevn/git-secret) | Git 内基于 GPG 的简单密钥共享 | | [BlackBox](https://github.com/StackExchange/blackbox) | 面向团队的 GPG 加密/解密 | | [transcrypt](https://github.com/elasticdog/transcrypt) | 针对选定路径的轻量级透明加密 | GitVault 的差异化优势：age 原生、确定性的逐字段重加密以最小化差异、结构化泄露防护，以及面向 AI-agent 工作流的运行时注入。 ## 许可证 根据以下任一许可证授权： - [Apache License, Version 2.0](LICENSE-APACHE) - [MIT license](LICENSE-MIT) 根据你的选择。

标签：Age加密, AI代理, DevSecOps, GitHooks, Git原生, Homebrew安装, JSONLines, Python安全, Rust, StruQ, 上游代理, 可视化界面, 团队协作, 密钥注入, 密钥轮换, 差分比较, 开发安全, 机密信息管理, 环境变量管理, 端到端加密, 网络安全研究, 网络流量审计, 身份管理, 通知系统, 通知系统, 通知系统, 防泄露, 零信任