# Show HN: Nimblegate – Git push guardrails for AI agents > Source: > Published: 2026-09-22 12:08:11+00:00 Git push guardrails for AI agents: block unsafe pushes consistently, forward safe ones, record every decision. **Status:** [· used in production since early 2026](https://github.com/nimblegate/nimblegate/releases/latest) nimblegate sits **between your AI agent and your real git host**. Every push your agent makes is checked against the rules you turned on; clean pushes forward to your upstream in under a second, unsafe ones are held with a clear report. Same input, same answer, every time. **→ Try the [live demo](https://demo.nimblegate.com): click through a real dashboard over sample data, nothing to install.** **→ New here? The [Getting Started guide](https://github.com/nimblegate/nimblegate/blob/main/docs/getting-started.md) walks you from install to your first guarded push, step by step, no git expertise assumed.** Self-hosted in one container. You need **Docker** with the **`docker compose`** plugin on the machine that runs the gateway. **1. Start the gateway.** ``` curl -O https://raw.githubusercontent.com/nimblegate/nimblegate/main/compose.yaml docker compose up -d ``` **Deploying to a fresh cloud VPS?** One file does the whole box: [`deploy/cloud-init.yaml`](https://github.com/nimblegate/nimblegate/blob/main/deploy/cloud-init.yaml) - paste it as user data at server creation and it boots hardened (firewall, key-only SSH) with the gateway running. **2. Claim the admin account.** Grab the one-time setup token, then set your password: ``` docker logs nimblegate | grep nbg-setup # prints the setup token ``` Open **[http://localhost:7900/setup](http://localhost:7900/setup)**, paste the token, choose your admin password. **Remote/headless host?** The dashboard binds the host's loopback (it's the admin surface). Tunnel to it: ``` ssh -L 7900:127.0.0.1:7900 @ # then open http://localhost:7900 ``` Use `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) **3. Register the repo to guard.** In the dashboard: **Repos → Add a repo**, then fill in: - **Name** - lowercase letters, numbers, dots, hyphens, underscores (e.g.`my-app` ). This is the name you'll push to. - **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. - **Upstream credential** - a**Personal Access Token** from your git host, scoped to**write that repo** : - GitHub **fine-grained** : repository = that repo,**Contents → Read and write** - GitHub **classic** : the`repo` scope - GitLab / Gitea: a token with write/push on the repo *(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).)* - GitHub Click **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) **4. Authorize your push key.** On your dev machine, print your SSH **public** key: ``` cat ~/.ssh/id_ed25519.pub ``` Copy 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. **5. Point your computer at the gateway and push.** Add the gateway as your remote and push to it instead of your real host. **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**. ``` git remote set-url origin ssh://git@:2222/~/my-app.git # my-app = the name from step 3 git push ``` **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. **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**. Bare-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. There are **three places**, and keeping them straight is the whole game: ``` 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 ``` - **Your computer only talks to the gateway:** you push to it and clone from it, never the upstream directly (that would skip the checks). - **Only the gateway talks to the upstream:** it holds the credential and forwards clean pushes for you. Your commits arrive at the upstream **byte-for-byte unchanged**: same SHA, same author, same signature. The gateway checks and forwards; it never rewrites. You see every push and decision live on the dashboard, and you can change the rules anytime; the next push uses the new set. **What that gets you:** - **Hours back on review.** The gate is the filter between an agent's output and your real repo, so you're not eye-scanning every generated diff yourself. - **Caught at push time, not deploy time.** Leaked credentials, force-pushes to main, schema drift: held at the gateway, never in your upstream history. - **A reviewer the fix-loop converges against.** "Push → fail → fix → pass" only works when the reviewer answers the same way every time. Pattern checks do; AI reviewers don't. - **Proof of what it stopped.** A live feed of every decision, plus a stats page estimating the hours saved. - **Invisible when clean.** A clean push forwards in under a second; the gate speaks up only when there's something to see. Full walkthrough with the mental model spelled out: **[Getting Started](https://github.com/nimblegate/nimblegate/blob/main/docs/getting-started.md)**. Because each of those either lives somewhere the agent can reach, or fires after the code has already landed. - **A pre-commit hook runs on the machine the agent controls.** It can be bypassed (`git push --no-verify` ), edited, or simply never installed in a fresh worktree. nimblegate runs on a separate box the agent has no shell on, and it holds the only credential to your real host - so there's nothing to skip and nowhere to go around. - **Branch protection and CODEOWNERS gate the *merge*, not the *push*.** By the time they fire, a leaked key is already an object in your upstream's history; deleting the branch doesn't unleak it, and rotating the credential is your only real remedy. The gate rejects the push, so the object never reaches your host at all. - **CI runs after the push landed** - and its config lives in the repo the agent is editing. Same exposure, one step later. - **The fix-loop needs a reviewer that answers the same way every time.** "Push → fail → fix → pass" only converges against a deterministic gate. Pattern checks are; an AI reviewer isn't. None 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. Day to day, the gate fits the normal feature-branch flow: 1. **Your agent works on a feature branch** - coding agents often use a git worktree per task, so several branches are in flight at once (one task, one branch) - and pushes it**to the gateway** . 2. The gate checks that push. **Clean** → forwarded to your upstream, where you or the agent open a PR (`feature → main` ), as usual.**Finding** →**rejected** , and the bad commit never reaches the upstream. 3. 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.) 4. **You review the PR and merge it to `main`** on your git host, as usual. Because rejected commits bounce at the gate, the branch on your upstream only ever holds gated-clean code - so by the time you review a PR, it has already passed the automated checks; you spend review time on judgment, not hunting for leaked keys or `rm -rf`. A new repo's **protected refs default to `refs/heads/*`**, so the agent's *feature* branches are gated, not just `main` - including nested names like `agent/task-1` or `feature/login`, since a trailing `/*` matches at any depth. Leave it there unless you deliberately want `main`-only checks. When a push is rejected, the gateway posts the findings as a **structured comment on the upstream PR** and fires a **webhook** with the same JSON, so an agent (Claude Code, Cursor, Copilot, custom CI) reads the rejection and fixes itself. The sticky comment updates in place, tracking **attempt N/M** and @-mentioning the agent; when a later push passes, it flips to **✅ All findings resolved** and the loop closes. The `/auto-pr` dashboard surfaces it as Dashboard / Repos / Activity / Setup tabs. Minimum config (per repo, `/auto-pr` → Setup or `gateway.toml`): set `[notification] enabled = true` and a mention handle and/or webhook URL. The upstream token needs **comment** permission (separate from the relay's push permission): **GitHub** - classic `repo`, or fine-grained **Issues: Read and write** + **Pull requests: Read** (PR comments use the Issues API); **Gitea** - `write:issue`; **GitLab** - the **` api`** scope (no narrower one allows MR comments). If deliveries fail, the **Auto-PR → Repos** tab shows the error + a **Retry now** button. Full setup + receiver examples: **[notifications.md](https://github.com/nimblegate/nimblegate/blob/main/docs/notifications.md)**. nimblegate ships **51 rules ("frames")** for the mistakes agents make most, grouped into one-click **kits**: - **`core`***(every repo)* : hardcoded credentials, committed private keys, force-push to protected branches,`--no-verify` bypass,`rm -rf` of protected paths,`curl | sh` patterns, DB schema drift, non-idempotent migrations. - **`web-app`** /**` cf-pages-project`** /**` cf-workers-project`** : stack-shaped bundles (HTML/SEO, Cloudflare Pages + D1, Workers). - **`security-strict`** /**` encoding-strict`** : the invisible-Unicode attack class, checksum-validated personal data in fixtures (payment cards, IBANs, SSNs), and paste-corruption that silently breaks parsers. Stackable on any kit. - **Supply-chain** :`commands/approved-registries-only` flags dependency sources (Maven/Gradle repositories, npm registries, pip index URLs) that bypass your approved registry mirror - declare your hosts once, catch the agent-added bypass at push time. Plus your own **regex rules**, authored from the dashboard with a live "would have flagged N files" preview: no code, no rebuild. Choosing and authoring policy: **[policy-authoring.md](https://github.com/nimblegate/nimblegate/blob/main/docs/policy-authoring.md)**. Full catalog: **[frames.md](https://github.com/nimblegate/nimblegate/blob/main/docs/frames.md)**. Every repo then runs those rules in one of two modes, set per repo: | | Enforce (default) | Observe ( `observe = true` ) | |---|---|---| | **BLOCK finding** | push **rejected** | recorded, **relayed** | | **Pusher / agent sees** | findings + `push rejected` | **nothing** , silent | | **Operator sees** | dashboard + audit log | dashboard + audit log (⚠ banner) | | **Acts as a guardrail?** | **yes** | **no, advisory only** | | **Use it for** | day-to-day protection | measuring/benchmarking agents | Observe mode is **deliberately silent** so an agent can't adapt to the gate; it measures behavior, it is **not** a safety net (a credential or `curl | sh` is logged and let through). Switching modes takes effect on the next push. The gateway exposes a read-only analytics API (MCP + REST) so an agent can query the decision log directly: *"which repo had the biggest bounce-back this month?"*, *"how much debugging time has the gate prevented?"*, *"what changed this week?"*, answered from SQL over the validated log. Mint a bearer token (`nimblegate gateway token new