知识花园

最近更新

安全实践、协作规范与工具生态

14分钟阅读

Git：安全实践、协作规范与工具生态

一个 API key 被提交进了仓库。发现后立刻删除——但 git 历史里永远有那条记录，而且在删除之前，CI 流水线可能已经把它打印进了日志，某个自动化的 clone 可能已经把整个历史下载走了。泄漏不一定来自攻击，往往来自一个没有防线的工作流里必然会发生的意外。

问题不是开发者不够小心，是安全边界设在了”发现问题”的地方，而不是”问题产生”的地方。把边界前移到 commit 时刻，大多数事故在发生之前就被拦截了。

Secret 扫描：双层防线

Secret 泄漏的典型路径是：本地提交 → 推送到远程 → CI 拉取并打印日志 → 日志被归档或被第三方服务捕获。每一步都在扩大泄漏面。最有效的拦截点是第一步——提交之前。

第一层：pre-commit 本地扫描

Gitleaks 是目前最流行的本地 secret 扫描工具，能识别数百种常见的密钥格式（AWS、GitHub token、数据库连接串、私钥文件等）：

# 安装
brew install gitleaks
 
# 扫描当前 staged 的内容（在 pre-commit hook 里调用）
gitleaks protect --staged
 
# 扫描整个仓库历史
gitleaks detect

配合 pre-commit hook，每次 git commit 之前自动运行。扫描到疑似 secret 时，提交被阻断，提示具体位置。

误报是不可避免的——测试文件里的假 key、文档里的示例字符串都可能触发规则。Gitleaks 支持 .gitleaks.toml 配置文件，可以定义 allowlist 排除特定路径或特定规则。allowlist 应该尽量窄，只豁免确认安全的内容，不应该用来绕过扫描本身。

第二层：CI 扫描作为兜底

本地 hook 可以被跳过（--no-verify），或者在没有配置 hook 的机器上失效。CI 里的扫描是第二道防线，覆盖所有推送到远程的提交。TruffleHog 扫描的不只是最新提交，而是整个 git 历史，能找出曾经存在过、后来被删除的 secret：

trufflehog git file://. --since-commit HEAD~10 --only-verified

在 GitHub Actions 里，TruffleHog 和 Gitleaks 都有官方的 Action，加进 CI workflow 不需要额外配置基础设施。

万一已经提交了

如果 secret 已经进了历史，删除那个文件或者新增一个 commit 覆盖是不够的——git 历史里的旧 commit 依然可以被检出。正确的处理方式是改写历史，用 git filter-repo（官方推荐的工具，替代已被废弃的 git filter-branch）把包含 secret 的内容从整个历史里清除：

# 安装
pip install git-filter-repo
 
# 把某个文件从整个历史里删除
git filter-repo --path secrets.env --invert-paths
 
# 替换历史里出现的特定字符串
git filter-repo --replace-text replacements.txt

改写历史之后必须 force push 到远程，所有已经 clone 过这个仓库的人需要重新 clone——他们本地的 objects 里还有旧历史。这个代价很高，正是为什么”在 commit 时刻拦截”比”事后清理”重要得多。与此同时，立刻撤销泄漏的 key，不要等历史清理完再撤销，因为历史清理需要时间，而 key 在那段时间里依然有效。

SSH commit 签名：身份的锚点

git 对象里的 author 字段是可以随意填写的。git config user.email 没有任何验证——任何人都可以把自己的 email 配置成别人的，提交看起来就像来自那个人。在开源项目或供应链安全要求高的场景里，这是一个真实的风险。

Commit 签名解决的是身份验证问题：用私钥对 commit 对象签名，任何拥有对应公钥的人都可以验证这个 commit 确实来自持有那把私钥的人。

现代工作流推荐用 SSH 密钥签名，而不是 GPG——同一把用于 GitHub 认证的 SSH 密钥可以同时用于签名，不需要额外管理 GPG 密钥环：

# 配置使用 SSH 格式签名
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
 
# 让所有 commit 自动签名
git config --global commit.gpgsign true
 
# 手动签名单次提交
git commit -S -m "feat: add payment integration"

在 GitHub 上，需要把同一把公钥同时添加为”Authentication Key”和”Signing Key”（两个独立的入口）。配置完成后，经过签名的 commit 在 GitHub 界面上会显示绿色的”Verified”徽章，未签名的显示”Unverified”。

团队可以在 GitHub 的仓库设置里开启”Require signed commits”分支保护规则，强制要求主干上的所有提交都经过签名。没有签名的 commit 无法直接推送到受保护的分支。

分支保护与 Merge Queue：主干的工程守卫

分支保护规则（Branch Protection Rules）是在平台层面对主干的约束，不依赖协作者的自觉性：

  • Require a pull request before merging：禁止直接推送到主干，所有改动必须经过 PR
  • Require status checks to pass：合并前 CI 必须通过，可以指定哪些 check 是必须的
  • Require approvals：至少需要几个 review 批准
  • Restrict force pushes：防止历史被意外改写
  • Require signed commits：只允许签名的提交

这些规则的价值不只是约束行为，是把”什么样的代码可以进主干”这件事变成可审计、可配置的工程策略，而不是靠团队约定和人工执行。

Merge Queue 解决的是一个更隐蔽的问题。

PR A 和 PR B 各自通过了 CI，同时等待合并。但 A 和 B 修改了相关联的代码，合并后的组合状态没有被测试过。A 先合并，B 再合并——B 在合并时 CI 检测的是 B 相对于合并前主干的状态，不是 B 加上 A 之后的状态。结果是主干绿了，但实际运行时出现问题。

Merge Queue 把这个问题系统化解决：待合并的 PR 进入队列，按顺序依次用”当前主干 + 该 PR”的组合状态运行 CI，只有验证通过才真正合并。多个 PR 同时在队列里时，每个 PR 的测试基础是”它之前所有已进队列的 PR 合并完成后的状态”——串行验证，消除了并发合并带来的不确定性。

GitHub 提供了原生的 Merge Queue（在分支保护规则里开启）。Mergify 是更灵活的第三方方案，支持更复杂的合并策略和优先级配置，在 GitHub 原生方案之前已经被很多团队采用。

Hooks 工具链：让规范低成本执行

.git/hooks/ 目录里的脚本会在特定 git 操作时自动触发，这是本地自动化的入口。三个最重要的 hook：

pre-commit：在 git commit 生成 commit 对象之前运行。适合放 lint、格式化、secret 扫描。如果脚本退出码非零，提交被阻断。

commit-msg：在 commit message 写入之后运行，接收 message 文件路径作为参数。适合用 commitlint 校验 Conventional Commits 格式。

pre-push：在 git push 发送数据之前运行。适合运行测试——但只适合速度足够快的测试套件，否则会让推送操作变得很慢，开发者会习惯性地用 --no-verify 跳过。

手动管理 .git/hooks/ 的问题是它不能随仓库一起提交——.git/ 目录不在版本控制里。Husky 和 Lefthook 解决了这个问题，把 hook 配置放在仓库根目录的配置文件里，通过 install 脚本写入 .git/hooks/：

Lefthook 是单个二进制文件，不依赖 Node.js 生态，支持并行执行多个命令，配置文件是 lefthook.yml。在跨语言项目或者想避免 Node.js 依赖的场景下更合适。

Husky 是 Node.js 生态里最普及的选择，和 npm install 无缝集成，配置直观，社区资料丰富。项目已经有 package.json 的情况下，Husky 是阻力最小的选择。

.gitignore 值得单独提一下，它不只是方便性工具，是防止意外提交的第一道墙。.env 文件、*.pem 密钥文件、IDE 配置文件、构建产物——这些都应该在 .gitignore 里显式排除，而不是依赖开发者每次手动不选。GitHub 维护了一个各语言的 .gitignore 模板仓库（github/gitignore），新建仓库时可以直接选用。

工具生态

lazygit 是终端 TUI，把 Git 的大多数日常操作变成可视化的键盘交互。查看文件改动、暂存特定区块、交互式 rebase、管理 stash——这些在命令行里需要多条命令配合的操作，在 lazygit 里通常是一两个按键。适合日常高频操作，不适合替代命令行的精细控制。

gh CLI 是 GitHub 的官方命令行工具，把 PR、issue、Actions、release 的管理带进终端：

gh pr create --fill          # 从当前分支和 commit message 自动填充 PR
gh pr view --web             # 在浏览器里打开当前 PR
gh pr checks                 # 查看 PR 的 CI 状态
gh run list                  # 查看 Actions 运行列表
gh run watch                 # 实时监听 Action 运行状态

在 CI 失败需要快速定位的场景下，gh run view --log-failed 直接拉取失败的日志比打开浏览器要快。

git-delta 改善了 git diff 的输出质量：语法高亮、行号、side-by-side 对比模式，以及更清晰的 merge conflict 展示。配置进 ~/.gitconfig 后对所有 diff 输出生效，包括 git log -p 和 git show。

tig 是另一个轻量的终端 TUI，专注于历史浏览——比 git log --graph 更直观，适合快速浏览提交历史和 diff，不需要离开终端。

关于 IDE 集成：VS Code 的 Source Control 面板和 JetBrains 的 Git 工具已经能处理绝大多数日常操作，对不熟悉命令行的协作者很友好。判断原则是：IDE 够用的时候用 IDE，需要精细控制（rebase -i、filter-repo、复杂的 reflog 操作）时回到命令行。两者不是替代关系，是在不同粒度上的工具选择。

关联

关系图谱