secrets-with-git-crypt

使用 Git-Crypt 进行密钥管理

本技能提供了一套安全、结构化的工作流，用于通过 git-crypt 管理仓库密钥（例如 .env、*.tfvars、sec.json、settings.json）。它指导 Agent 确保敏感凭据绝不会以明文形式提交，而是维护并提交与之对应的加密 .enc 版本到 Git 中。

目录

• 触发条件
• 前置条件
• 密钥设置与同步工作流
• 命令参考
• 验证循环

触发条件

本技能必须在以下情况触发：

• 用户提到 git-crypt、encryption、decryption 或 secrets management。
• 用户请求将敏感文件（如 .env、*.tfvars、settings.json、密钥文件）存储到仓库中。
• 用户尝试将应加密的文件（例如 .env、*.tfvars、sec.json）提交或推送到仓库。
• 克隆一个包含 .enc 文件（例如 .env.enc、terraform.tfvars.enc、settings.json.enc）的现有仓库，表明该仓库之前受 git-crypt 保护。
• 初始化新仓库并设置本地/远程密钥配置。
• 更改或添加需要安全提交的密钥凭据。

前置条件

• 宿主环境：类 Unix 操作系统（例如 Linux、WSL、macOS）。
• Git：必须在当前项目中初始化一个 git 仓库。
• git-crypt：必须安装 git-crypt 命令行工具。
  • 如果缺失，辅助脚本可以尝试在 Debian/Ubuntu 系统上通过 sudo apt-get install git-crypt 进行安装。
• 辅助脚本：确保位于 skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh 的辅助脚本具有可执行权限（chmod +x）。

密钥设置与同步工作流

复制此清单并跟踪你的进度：

Secrets Management Progress:
- [ ] Step 1: Verify git-crypt installation
- [ ] Step 2: Initialize or unlock the repository
- [ ] Step 3: Configure tracking and gitignore rules
- [ ] Step 4: Perform file synchronization
- [ ] Step 5: Verify environment security

步骤 1：实现前的安全性与二进制文件验证

在尝试任何加密、解密或密钥同步操作之前：

1. 验证 Git 工作树：

   • 确认工作目录位于 Git 仓库内（git rev-parse --is-inside-work-tree）。如果不在 Git 仓库中，停止执行并提示用户先运行 git init。

2. 验证 git-crypt 二进制文件与辅助脚本：

   • 确保位于 skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh 的辅助脚本具有可执行权限（chmod +x）。
   • 运行辅助脚本的状态命令，检查 git-crypt 是否已安装并正常工作：

     ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh status
     

   • 如果缺少 git-crypt，提供通过以下方式安装的选项：

     ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh install
     

步骤 2：初始化或解锁仓库

• 如果这是一个新仓库（或者你是首次设置 git-crypt）： 决定安全密钥将存储在仓库之外的哪个位置（例如 ~/secure-keys/my-project.key）。主动运行：

  ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh init ~/secure-keys/my-project.key
  

  确保密钥永远不会被提交到 git。

• 如果这是一个包含 .enc 文件的克隆仓库： 询问用户现有密钥文件的本地路径，并运行：

  ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh unlock /path/to/existing.key
  

步骤 3：配置跟踪与 gitignore 规则

验证项目根目录下的 .gitattributes 包含过滤器声明：

*.enc filter=git-crypt diff=git-crypt

所有未加密文件（例如 .env、settings.json、variables.tfvars）必须显式添加到 .gitignore 中。运行辅助脚本的同步命令会自动追加它们，但你必须仔细检查它们没有以明文形式被 Git 跟踪。

步骤 4：执行文件同步

• 同步到加密版本（提交更改之前）： 将未加密的本地文件复制到其对应的 .enc 版本：

  • 针对特定文件：

    ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh sync-to-enc .env
    

  • 针对仓库中所有已知的 .enc 文件：

    ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh sync-to-enc
    

• 从加密版本同步（解锁克隆仓库之后）： 从已解锁的 .enc 版本恢复所有未加密的明文文件：

  ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh sync-from-enc
  

步骤 5：验证环境安全性

在结束本轮之前，执行验证循环中的步骤，以确保没有明文密钥被暂存或提交。

---

命令参考

辅助脚本支持以下命令：

命令	参数	描述
install	无	在 Debian/Ubuntu/WSL 平台上安装 git-crypt。
init	<key_path>	运行 git-crypt init，设置 .gitattributes，并导出密钥。
unlock	<key_path>	使用指定的密钥文件解锁仓库。
sync-to-enc	[file]	将未加密文件同步到其 .enc 副本；确保包含在 .gitignore 中。
sync-from-enc	[file]	将 .enc 副本同步/恢复回未加密文件。
status	无	评估安装、git-crypt 初始化以及文件同步状态。

---

验证循环

在结束密钥设置或修改之前，Agent 必须执行以下验证步骤：

1. 执行状态检查

运行辅助状态命令：

./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh status

确保所有对应的密钥文件都报告 [OK]。如果有任何文件显示 DO NOT MATCH，请运行相应的 sync-to-enc 或 sync-from-enc 命令。

2. 验证 gitignore 完整性

确认未加密的明文文件未被 Git 跟踪。运行：

git ls-files --error-unmatch .env 2>/dev/null

• 如果命令返回输出（文件被跟踪）：立即运行 git rm --cached <file> 将其从暂存区移除，同时保留在本地磁盘上。

3. 验证 .gitattributes 结构

验证 .gitattributes 中是否包含：

*.enc filter=git-crypt diff=git-crypt

这确保 git-crypt 能在 Git 下透明地管理所有 .enc 文件。

4. 检查 Git Crypt 状态

验证 git-crypt 是否正确匹配已暂存/已提交的 .enc 文件：

git-crypt status

输出必须显示这些 .enc 文件为 encrypted。