nimblegate/nimblegate
GitHub: nimblegate/nimblegate
nimblegate 是一款自托管的 Git push 网关，在 AI agent 与真实 Git 仓库之间拦截不安全推送并转发安全推送，同时记录所有决策。
Stars: 0 | Forks: 0
# nimblegate
**状态：** v0.1.0 · 自 2026 年初起用于生产环境
nimblegate 位于**你的 AI agent 和真实的 git host 之间**。你的 agent 进行的每一次 push 都会根据你开启的规则进行检查；干净的 push 会在一秒内转发到你的 upstream，不安全的 push 会被拦截并附带清晰的报告。相同的输入，每次都会得到相同的答案。
**→ 试试 [在线演示](https://demo.nimblegate.com)：浏览基于示例数据的真实仪表板，无需安装任何内容。**
**→ 新手？[入门指南](docs/getting-started.md) 将一步步带你从安装到完成第一次受保护的 push，无需任何 git 经验。**
## 目录
- [快速安装](#quick-install)
- [工作原理](#how-it-works)
- [工作流](#the-workflow)
- [Auto-PR：agent 修复循环](#auto-pr-the-agent-fix-loop)
- [它能拦截什么以及如何运作](#what-it-catches-and-how-it-acts)
- [面向 agent 的 MCP 分析](#mcp-analytics-for-agents)
- [指南](#guides)
- [职责所在](#where-the-responsibility-lives)
- [非商业版本包含的内容](#whats-in-the-non-commercial-version)
- [商业用途 · License · 隐私](#commercial-use)
## 快速安装
在单个 container 中实现自托管。你需要在运行网关的机器上安装带有 **`docker compose`** 插件的 **Docker**。
**1. 启动网关。**
```
curl -O https://raw.githubusercontent.com/nimblegate/nimblegate/main/compose.yaml
docker compose up -d
```
**2. 认领管理员账号。** 获取一次性设置 token，然后设置你的密码：
```
docker logs nimblegate | grep nbg-setup # prints the setup token
```
打开 **http://localhost:7900/setup**，粘贴 token，选择你的管理员密码。
**3. 注册要受保护的 repo。** 在仪表板中：**Repos → Add a repo**，然后填写：
- **Name** - 字母、数字、连字符（例如 `my-app`）。这是你要 push 的目标名称。
- **Upstream URL** - 你的真实 repo 地址，必须是 **HTTPS** 格式：`https://github.com/you/my-app.git`（而不是 `git@…` SSH 形式）。container 仅通过 **HTTPS** 进行中继 - 设计上它不包含 SSH 客户端 - 并且 PAT 对**公共和私有** repo 进行身份验证。
- **Upstream credential** - 来自你的 git host 的 **Personal Access Token**，其权限范围限定为**写入该 repo**：
- GitHub **fine-grained**：repository = 该 repo，**Contents → Read and write**
- GitHub **classic**：`repo` scope
- GitLab / Gitea：具有对该 repo 写入/push 权限的 token
*(Auto-PR 的修复循环需要更多权限 - 请参阅 [入门指南](docs/getting-started.md#step-4-register-the-repo-to-guard)。)*
点击 **Register**。如果 upstream **已经有 commits**，请点击 repo 行上的 **Sync from upstream**，以便网关同步其当前历史记录（这样你现有的 clones 就能顺利 push） - 全新的/空的 upstream 不需要同步。**core** 规则套件会自动应用。 → [其他 git hosts，作用域访问](docs/getting-started.md)
**4. 授权你的 push key。** 在你的开发机器上，打印你的 SSH **public** key：
```
cat ~/.ssh/id_ed25519.pub
```
复制整行，然后在仪表板中转到 **Keys → Add a key**，粘贴并保存。网关只会看到你的 **public** key - 永远不会看到私钥。
**5. 将你的计算机指向网关并 push。** 将网关添加为你的 remote，并 push 到它而不是你的真实 host。
```
git remote set-url origin ssh://git@:2222/~/my-app.git # my-app = the name from step 3
git push
```
**6. 查看运行效果。** 干净的 push 会被接受并转发到你的 upstream；触发规则的 push 会被拦截，永远不会到达真实 host。在仪表板的 **Feed** 中实时查看。
需要裸机安装、SSH-key upstreams、多开发人员作用域访问或公共 TLS？ → **[入门指南](docs/getting-started.md)** - 完整的演练 + 故障排除。
## 工作原理
这里有**三个位置**，理清它们是整个游戏的关键：
```
YOUR COMPUTER THE GATEWAY THE UPSTREAM
(you / your agent (nimblegate) (GitHub / Gitea / GitLab:
write + git push) your real repo)
git push ──────────────────► checks your rules ─forwards─► stores the code
git clone ◄───────────────── serves the code
```
- **你的计算机只与网关通信：** 你 push 到它并从中 clone，
永远不会直接连接 upstream（那会跳过检查）。
- **只有网关与 upstream 通信：** 它持有凭证，
并为你转发干净的 push。
你的 commits 到达 upstream 时**逐字节保持不变**：相同的 SHA、相同的 author、相同的 signature。网关只负责检查和转发；它从不重写。你可以在仪表板上实时看到每一次 push 和决定，并且你可以随时更改规则；下一次 push 将使用新规则集。
**这能为你带来什么：**
- **节省审查时间。** 网关是 agent 输出与你真实 repo 之间的过滤器，
因此你不必亲自逐个肉眼检查每个生成的 diff。
- **在 push 时拦截，而不是在部署时。** 泄露的凭证、向 main 的 force-push、schema drift：在网关处被拦截，永远不会进入你的 upstream 历史。
- **一个修复循环能够收敛的审查者。** “Push → 失败 → 修复 → 通过”只在审查者每次回答一致时才有效。模式检查可以做到；AI 审查者做不到。
- **拦截记录证明。** 每个决定的实时 feed，加上一个估算节省时间的统计页面。
- **干净时隐形。** 干净的 push 在一秒内转发；只有在有内容需要查看时，网关才会发声。
详细说明心智模型的完整演练：**[入门指南](docs/getting-started.md)**。
## 工作流
在日常使用中，网关契合正常的功能分支流：
1. **你的 agent 在功能分支上工作** - 编码 agent 通常为每个任务使用一个 git
worktree，因此同时进行着多个分支（一个任务，一个分支） - 并将其 push **到网关**。
2. 网关检查该 push。**干净** → 转发到你的 upstream，在那里会开启一个 PR
（`feature → main`）。**发现** → **拒绝**，并且糟糕的 commit
永远不会到达 upstream。
3. 在拒绝且已有打开的 PR 时，网关会将该发现作为 PR 评论发布
（参见下文的 Auto-PR） - agent 阅读它，进行修复，然后重新 push 直到通过。
4. **你像往常一样在你的 git host 上审查 PR 并将其合并到 `main`**。
因为被拒绝的 commits 在网关处被拦截，你 upstream 上的分支只
包含经过网关检查的干净代码 - 因此当你审查 PR 时，它已经
通过了自动化检查；你可以将审查时间花在判断上，而不是寻找泄露的 key 或 `rm -rf`。将 repo 的 **protected refs 设置为 `refs/heads/*`**，以便 agent 的 *feature* 分支受网关保护，而不仅仅是 `main`。
## Auto-PR：agent 修复循环
当 push 被拒绝时，网关会将发现结果作为**结构化评论发布在 upstream PR 上**，并触发一个带有相同 JSON 的 **webhook**，以便 agent（Claude Code、Cursor、Copilot、自定义 CI）读取拒绝信息并自行修复。
置顶评论会就地更新，跟踪 **尝试 N/M** 并 @-提及该 agent；当随后的 push 通过时，它会翻转为 **✅ 所有问题已解决**，循环关闭。`/auto-pr` 仪表板将其显示为 Dashboard / Repos / Activity / Setup 标签页。
最低配置（针对每个 repo，`/auto-pr` → Setup 或 `gateway.toml`）：设置
`[notification] enabled = true` 以及一个提及的 handle 和/或 webhook URL。
upstream token 需要 **comment** 权限（与中继的 push 权限分开）：**GitHub** - classic `repo`，或 fine-grained **Issues: Read and write** + **Pull requests: Read**（PR 评论使用 Issues API）；**Gitea** -
`write:issue`；**GitLab** - **`api`** scope（没有更窄的范围允许 MR 评论）。如果投递失败，**Auto-PR → Repos** 标签页会显示错误 +
一个 **Retry now** 按钮。完整设置 + 接收器示例：
**[notifications.md](docs/notifications.md)**。
## 它能拦截什么以及如何运作
nimblegate 内置了 **45 条规则（“frames”）**，专门针对 agent 最常犯的错误，并将其分组为一键式 **kits**：
- **`core`** *（每个 repo）*：硬编码的凭证、提交的私钥、
向受保护分支的 force-push、`--no-verify` 绕过、对受保护路径的 `rm -rf`、`curl | sh` 模式、DB schema drift、非幂等迁移。
- **`web-app`** / **`cf-pages-project`** / **`cf-workers-project`**：特定 stack 的
捆绑包（HTML/SEO、Cloudflare Pages + D1、Workers）。
- **`security-strict`** / **`encoding-strict`**：不可见 Unicode 攻击
类别以及因粘贴损坏而静默破坏解析器的问题。可叠加在任何 kit 上。
此外还有你自己的 **regex 规则**，可以直接在仪表板上编写，并带有实时的“将标记 N 个文件”预览：无需代码，无需重新构建。选择和编写策略：
**[policy-authoring.md](docs/policy-authoring.md)**。完整目录：
**[frames.md](docs/frames.md)**。
然后，每个 repo 会以以下两种模式之一运行这些规则，可针对每个 repo 进行设置：
| | Enforce（默认） | Observe（`observe = true`） |
|---|---|---|
| **拦截发现** | push **被拒绝** | 记录，**已中继** |
| **Pusher / agent 看到的内容** | 发现 + `push rejected` | **什么都没有**，静默 |
| **Operator 看到的内容** | 仪表板 + 审计日志 | 仪表板 + 审计日志（⚠ 横幅） |
| **充当护栏？** | **是** | **否，仅供参考** |
| **用于** | 日常保护 | 衡量/基准测试 agent |
Observe 模式是**故意静默的**，以便 agent 无法适应网关；它衡量的是行为，**不是**安全网（凭证或 `curl | sh` 会被记录并放行）。切换模式会在下一次 push 时生效。
## 面向 agent 的 MCP 分析
网关公开了一个只读分析 API（MCP + REST），以便 agent 可以直接查询决定日志：*“本月哪个 repo 的退回次数最多？”*，*“网关避免了多少调试时间？”*，*“本周发生了什么变化？”*，这些都可以通过基于验证日志的 SQL 来回答。生成一个 bearer token
（`nimblegate gateway token new
标签：AI代理, DevSecOps, EVTX分析, Git, 上游代理, 代码安全审查, 内存分配, 版权保护, 网关, 网络安全研究, 请求拦截