{"slug": "show-hn-nimblegate-git-push-guardrails-for-ai-agents", "title": "Show HN: Nimblegate – Git push guardrails for AI agents", "summary": "Nimblegate launched a self-hosted gateway that sits between an AI agent and a real git host, checking every push against enabled rules and forwarding clean pushes upstream in under a second while holding unsafe ones with a report. The tool, in production since early 2026, ships as a single Docker container with a docker compose plugin, a dashboard on port 7900, and a core rule kit of 18 of 51 frames that applies automatically at repo registration. Repos are registered with an HTTPS upstream URL and a write-scoped Personal Access Token, and the gateway relays over HTTPS only, shipping without an SSH client by design.", "body_md": "Git push guardrails for AI agents: block unsafe pushes consistently, forward safe ones, record every decision.\n\n**Status:** [· used in production since early 2026](https://github.com/nimblegate/nimblegate/releases/latest)\n\nnimblegate sits **between your AI agent and your real git host**. Every push your\nagent makes is checked against the rules you turned on; clean pushes forward to\nyour upstream in under a second, unsafe ones are held with a clear report. Same\ninput, same answer, every time.\n\n**→ Try the [live demo](https://demo.nimblegate.com): click through a real dashboard over sample data, nothing to install.**\n\n**→ New here? The [Getting Started guide](https://github.com/nimblegate/nimblegate/blob/main/docs/getting-started.md) walks you from\ninstall to your first guarded push, step by step, no git expertise assumed.**\n\nSelf-hosted in one container. You need **Docker** with the **`docker compose`** plugin on the\nmachine that runs the gateway.\n\n**1. Start the gateway.**\n\n```\ncurl -O https://raw.githubusercontent.com/nimblegate/nimblegate/main/compose.yaml\ndocker compose up -d\n```\n\n**Deploying to a fresh cloud VPS?** One file does the whole box:\n[`deploy/cloud-init.yaml`](https://github.com/nimblegate/nimblegate/blob/main/deploy/cloud-init.yaml) - paste it as user data at\nserver creation and it boots hardened (firewall, key-only SSH) with the\ngateway running.\n\n**2. Claim the admin account.** Grab the one-time setup token, then set your password:\n\n```\ndocker logs nimblegate | grep nbg-setup # prints the setup token\n```\n\nOpen **[http://localhost:7900/setup](http://localhost:7900/setup)**, paste the token, choose your admin password.\n\n**Remote/headless host?** The dashboard binds the host's loopback (it's the admin surface). Tunnel to it:\n\n```\nssh -L 7900:127.0.0.1:7900 @ # then open http://localhost:7900\n```\n\nUse `127.0.0.1`, **not** `localhost` (it's published on IPv4). For a trusted LAN instead, set `NIMBLEGATE_DASHBOARD_HOST=0.0.0.0`. → [dashboard access options](https://github.com/nimblegate/nimblegate/blob/main/docs/getting-started.md#dashboard-access)\n\n**3. Register the repo to guard.** In the dashboard: **Repos → Add a repo**, then fill in:\n\n- \n**Name** - lowercase letters, numbers, dots, hyphens, underscores (e.g.`my-app` ). This is the name you'll push to.\n- \n**Upstream URL** - your real repo as**HTTPS** :`https://github.com/you/my-app.git` (not the`git@…` SSH form). The container relays over**HTTPS only** - it ships without an SSH client by design - and a PAT authenticates**both public and private** repos.\n- \n**Upstream credential** - a**Personal Access Token** from your git host, scoped to**write that repo** :\n - GitHub **fine-grained** : repository = that repo,**Contents → Read and write**\n - GitHub **classic** : the`repo` scope\n - GitLab / Gitea: a token with write/push on the repo\n *(Auto-PR's fix-loop needs a little more - see [Getting Started](https://github.com/nimblegate/nimblegate/blob/main/docs/getting-started.md#step-4-register-the-repo-to-guard).)*\n- GitHub \n\nClick **Register**. If the upstream **already has commits**, the gateway mirrors its history down automatically at registration, so your existing clones push cleanly. If that seed couldn't run (a missing or wrong credential, say), the repo row shows a one-click **Sync from upstream** - fix the credential, click it, done. The **core** rule kit (18 of the 51 frames, the catastrophic-prevention set) applies automatically; widen or narrow it any time on the repo's Policy page. → [other git hosts, scoped access](https://github.com/nimblegate/nimblegate/blob/main/docs/getting-started.md)\n\n**4. Authorize your push key.** On your dev machine, print your SSH **public** key:\n\n```\ncat ~/.ssh/id_ed25519.pub\n```\n\nCopy the whole line, then in the dashboard go to **Keys → Add a key**, paste it, and save. The gateway only ever sees your **public** key - never the private one.\n\n**5. Point your computer at the gateway and push.** Add the gateway as your remote and push to it instead of your real host.\n\n**This hop is SSH, not HTTPS.** You push to the gateway over **SSH on port 2222** - that's *not* the HTTPS upstream URL from step 3. The two hops use different protocols on purpose: **your machine → gateway = SSH**, **gateway → your real host = HTTPS**.\n\n```\ngit remote set-url origin ssh://git@:2222/~/my-app.git # my-app = the name from step 3\ngit push\n```\n\n**Note the `~/` in the URL** - it's required, not a typo. On the gateway the SSH user is locked to **git-shell** (it can run git push/clone and *nothing* else - no shell, no commands), which resolves repo paths relative to its home. So the path is `~/.git`, not a bare `/.git`. This restriction is a security feature: a key can only move git data through the gate, never run commands or read the gateway's upstream token - so a compromised dev key can't bypass the gate or steal your credential.\n\n**6. See it work.** A clean push is accepted and forwarded to your upstream; a push that trips a rule is blocked and never reaches the real host. Watch it live on the dashboard **Feed**.\n\nBare-metal install, SSH-key upstreams, multi-dev scoped access, or public TLS? → **[Getting Started](https://github.com/nimblegate/nimblegate/blob/main/docs/getting-started.md)** - full walkthrough + troubleshooting.\n\nThere are **three places**, and keeping them straight is the whole game:\n\n```\n YOUR COMPUTER THE GATEWAY THE UPSTREAM\n (you / your agent (nimblegate) (GitHub / Gitea / GitLab:\n write + git push) your real repo)\n\n git push ──────────────────► checks your rules ─forwards─► stores the code\n git clone ◄───────────────── serves the code\n```\n\n- **Your computer only talks to the gateway:** you push to it and clone from it,\nnever the upstream directly (that would skip the checks).\n- **Only the gateway talks to the upstream:** it holds the credential and\nforwards clean pushes for you.\n\nYour commits arrive at the upstream **byte-for-byte unchanged**: same SHA, same\nauthor, same signature. The gateway checks and forwards; it never rewrites. You\nsee every push and decision live on the dashboard, and you can change the rules\nanytime; the next push uses the new set.\n\n**What that gets you:**\n\n- **Hours back on review.** The gate is the filter between an agent's output and\nyour real repo, so you're not eye-scanning every generated diff yourself.\n- **Caught at push time, not deploy time.** Leaked credentials, force-pushes to\nmain, schema drift: held at the gateway, never in your upstream history.\n- **A reviewer the fix-loop converges against.** \"Push → fail → fix → pass\" only\nworks when the reviewer answers the same way every time. Pattern checks do; AI\nreviewers don't.\n- **Proof of what it stopped.** A live feed of every decision, plus a stats page\nestimating the hours saved.\n- **Invisible when clean.** A clean push forwards in under a second; the gate\nspeaks up only when there's something to see.\n\nFull walkthrough with the mental model spelled out: **[Getting\nStarted](https://github.com/nimblegate/nimblegate/blob/main/docs/getting-started.md)**.\n\nBecause each of those either lives somewhere the agent can reach, or fires after the code has already landed.\n\n- **A pre-commit hook runs on the machine the agent controls.** It can be\nbypassed (`git push --no-verify` ), edited, or simply never installed in a fresh\nworktree. nimblegate runs on a separate box the agent has no shell on, and it\nholds the only credential to your real host - so there's nothing to skip and\nnowhere to go around.\n- **Branch protection and CODEOWNERS gate the *merge*, not the *push*.** By the\ntime they fire, a leaked key is already an object in your upstream's history;\ndeleting the branch doesn't unleak it, and rotating the credential is your only\nreal remedy. The gate rejects the push, so the object never reaches your host\nat all.\n- **CI runs after the push landed** - and its config lives in the repo the agent\nis editing. Same exposure, one step later.\n- **The fix-loop needs a reviewer that answers the same way every time.** \"Push →\nfail → fix → pass\" only converges against a deterministic gate. Pattern checks\nare; an AI reviewer isn't.\n\nNone of these replace each other - keep your hooks and your branch protection. The gate is the one layer that sits outside the machine writing the code.\n\nDay to day, the gate fits the normal feature-branch flow:\n\n1. **Your agent works on a feature branch** - coding agents often use a git\nworktree per task, so several branches are in flight at once (one task, one\nbranch) - and pushes it**to the gateway** .\n2. The gate checks that push. **Clean** → forwarded to your upstream, where you\nor the agent open a PR (`feature → main` ), as usual.**Finding** →**rejected** , and the bad commit never reaches the upstream.\n3. On a rejection with an open PR, the gate posts the finding as a PR comment (see Auto-PR below) - the agent reads it, fixes, and re-pushes until it passes. (The gate comments on a PR; it doesn't open one - your git host does that.)\n4. **You review the PR and merge it to `main`** on your git host, as usual.\n\nBecause rejected commits bounce at the gate, the branch on your upstream only\never holds gated-clean code - so by the time you review a PR, it has already\npassed the automated checks; you spend review time on judgment, not hunting for\nleaked keys or `rm -rf`. A new repo's **protected refs default to `refs/heads/*`**,\nso the agent's *feature* branches are gated, not just `main` - including nested\nnames like `agent/task-1` or `feature/login`, since a trailing `/*` matches at any\ndepth. Leave it there unless you deliberately want `main`-only checks.\n\nWhen a push is rejected, the gateway posts the findings as a **structured comment\non the upstream PR** and fires a **webhook** with the same JSON, so an agent\n(Claude Code, Cursor, Copilot, custom CI) reads the rejection and fixes itself.\nThe sticky comment updates in place, tracking **attempt N/M** and @-mentioning the\nagent; when a later push passes, it flips to **✅ All findings resolved** and the\nloop closes. The `/auto-pr` dashboard surfaces it as Dashboard / Repos / Activity\n/ Setup tabs.\n\nMinimum config (per repo, `/auto-pr` → Setup or `gateway.toml`): set\n`[notification] enabled = true` and a mention handle and/or webhook URL. The\nupstream token needs **comment** permission (separate from the relay's push\npermission): **GitHub** - classic `repo`, or fine-grained **Issues: Read and\nwrite** + **Pull requests: Read** (PR comments use the Issues API); **Gitea** -\n`write:issue`; **GitLab** - the **` api`** scope (no narrower one allows MR\ncomments). If deliveries fail, the **Auto-PR → Repos** tab shows the error +\na **Retry now** button. Full setup + receiver examples:\n**[notifications.md](https://github.com/nimblegate/nimblegate/blob/main/docs/notifications.md)**.\n\nnimblegate ships **51 rules (\"frames\")** for the mistakes agents make most, grouped\ninto one-click **kits**:\n\n- **`core`***(every repo)* : hardcoded credentials, committed private keys,\nforce-push to protected branches,`--no-verify` bypass,`rm -rf` of protected\npaths,`curl | sh` patterns, DB schema drift, non-idempotent migrations.\n- **`web-app`** /**` cf-pages-project`** /**` cf-workers-project`** : stack-shaped\nbundles (HTML/SEO, Cloudflare Pages + D1, Workers).\n- **`security-strict`** /**` encoding-strict`** : the invisible-Unicode attack\nclass, checksum-validated personal data in fixtures (payment cards, IBANs,\nSSNs), and paste-corruption that silently breaks parsers. Stackable on any kit.\n- **Supply-chain** :`commands/approved-registries-only` flags dependency\nsources (Maven/Gradle repositories, npm registries, pip index URLs) that\nbypass your approved registry mirror - declare your\nhosts once, catch the agent-added bypass at push time.\n\nPlus your own **regex rules**, authored from the dashboard with a live \"would have\nflagged N files\" preview: no code, no rebuild. Choosing and authoring policy:\n**[policy-authoring.md](https://github.com/nimblegate/nimblegate/blob/main/docs/policy-authoring.md)**. Full catalog:\n**[frames.md](https://github.com/nimblegate/nimblegate/blob/main/docs/frames.md)**.\n\nEvery repo then runs those rules in one of two modes, set per repo:\n\n| | Enforce (default) | Observe ( `observe = true` ) | \n|---|---|---|\n| **BLOCK finding** | push **rejected** | recorded, **relayed** | \n| **Pusher / agent sees** | findings + `push rejected` | **nothing** , silent | \n| **Operator sees** | dashboard + audit log | dashboard + audit log (⚠ banner) | \n| **Acts as a guardrail?** | **yes** | **no, advisory only** | \n| **Use it for** | day-to-day protection | measuring/benchmarking agents | \n\nObserve mode is **deliberately silent** so an agent can't adapt to the gate; it\nmeasures behavior, it is **not** a safety net (a credential or `curl | sh` is\nlogged and let through). Switching modes takes effect on the next push.\n\nThe gateway exposes a read-only analytics API (MCP + REST) so an agent can query\nthe decision log directly: *\"which repo had the biggest bounce-back this month?\"*,\n*\"how much debugging time has the gate prevented?\"*, *\"what changed this week?\"*,\nanswered from SQL over the validated log. Mint a bearer token\n(`nimblegate gateway token new