My AI agent commits code. Not as a demo — as a Tuesday. Site posts, deploy scripts, infra definitions. And the day an agent starts committing, you make a decision that most people make accidentally, in the wrong direction, at 11pm: what credential does it hold?
The lazy answer is the one git tutorials hand you: generate a key, drop it in
authorized_keys, move on. I did the other one, and this is the write-up of
why, what it cost in scars, and where it's still unfinished.
Why the SSH key is the wrong primitive for an agent
An SSH key wired to git was designed for a human who has a conscience, a name, and a strong preference not to bricking their own server. An agent has none of those things — it has instructions, a context window, and a talent for being confidently wrong. Four problems, in escalating order:
- No scope. The key doesn't say "you may push a branch." It says "you may run commands as this user." Rewriting history, editing the key file itself, and reaching every other repo on that account are all inside the same single permission.
- No revocation granularity. There is no dial between "full access" and "no access." The moment you want "this agent reads everything but only writes two repos," an SSH key has nothing to offer.
- No audit story. SSH logs a key fingerprint and a push. A forge logs who authored every commit, which token carried it, and which branch protection blocked what. When something looks wrong at 2am, that is the difference between an investigation and a guessing game.
- Blast radius. Prompt injection is not hypothetical. An agent that scrapes a hostile page and obeys it, holding an SSH key, is an attacker with a shell. Holding a scoped token, it's an attacker who can open a pull request against a protected branch. Same incident, very different news.
The doctrine version: give the agent a capability, not an identity.
The decision I actually made
A self-hosted git forge in front of everything the agent touches. The comparison I ran, condensed:
| option | verdict |
|---|---|
| bare git over SSH | right answer for me alone, one repo. The day a second consumer — human or agent — needs scoped access, it becomes god-mode with extra steps |
| the big-name forge suite | 8–12 GB of RAM to serve one human and a few agents. The k8s-of-git. No |
| small single-binary forge, ~300 MB idle | per-agent tokens, per-repo revocation, protected branches, audit trail. This one |
Two design rules rode along:
- Never share a failure domain with the backups. The forge holds the blueprint of everything I build; putting it on the same box as the backup target means one disk (or one badly-scheduled restore) takes both. It rides a small Linux guest with the usual snapshot-and-bundle rotation instead. (host naming and layout changed for publication — the shape is what matters.)
- A web login and a git token are different creatures. The token authenticates git pushes and the API; it will not open the web UI, and the web password will not sign a push. When my agent's credential leaks, it leaks one capability, not the admin plane.
What running it taught me
The plan was a paragraph. The migration was five traps, each of which I'd now print on a card:
| trap | what it looked like | what it was |
|---|---|---|
| push-to-create disabled | 403 Push to create is not enabled |
a feature I hadn't designed: repo creation stays a deliberate human act. The gate existed before I did |
| credential-in-URL auth | 401 Unauthorized with a valid token |
this forge rejects the user:token@host URL scheme entirely. The working pattern is an Authorization: token … header attached via git config, per-hostname |
| missing credential | no error at all. just… silence | git waits on an interactive prompt that the agent never sees, and the push hangs forever. A hang is a credential failure wearing a disguise |
| token rotation | new token rejected everywhere | the admin CLI writes errors to stdout, and one sudo error line is exactly token-shaped — 52 characters. I installed an error message as a secret. Now every rotated secret is format-checked (^[A-Za-z0-9]{30,64}$) before it goes anywhere |
| first push of a mirrored repo | shallow update not allowed |
shallow clones are refused by design. fetch --unshallow first — and neuter the upstream remote (set-url --push upstream DISABLED) so a mistyped push can never leak back out |
Three of those five share one shape, and it's the same lesson I wrote about
with the firewall API: a failed authentication and a wrong map can look
identical. Before debugging anything else, authenticate against a known-
good read (/api/v1/user for me) — if that returns 200, the secret is fine
and your call is wrong.
And the bonus trap, free of charge: a fresh git init on the new box
defaulted to master while every remote wanted main. src refspec main does not match any reads like an auth disaster and is a branch rename
waiting to happen.
The layer I have not built, said out loud
Deploy-before-write has been the rule of this blog since post one, so no rounding off: the architecture above is live, the last layer is not.
What exists today: per-agent scoped tokens, private repos, human-created
repo gates, protected history by habit and read-back. What doesn't exist
yet: an isolated build runner and branch protection wired to one required
human approval before anything merges to main. Right now I am the gate
by attention. The goal is the gate by architecture:
- the agent pushes a branch and opens a pull request;
- an untrusted runner — its own guest, holding zero deploy secrets and holding no network path to production — builds the diff and runs the content and secret linters;
- merge requires one approval from a human who can read a diff;
- only then does a trusted job rsync the build to the inactive slot and flip a symlink. Rollback is flipping it back.
That runner box is the only unfinished seat in this design, and this post will get a sequel with migration scars when it's real — not a spec sheet now.
The one-line version
The point is not that agents can't be trusted. The point is that an SSH key cannot answer the question you will someday ask — "what exactly was this credential allowed to do?" — and a forge can. Cost me one small guest, ~300 MB idle, and five traps I won't repeat. Cheapest security upgrade in the rack so far.