Building VeloGit: An Open-Source Git Platform for the Agent Era

I. Why Another Git Platform?

The major Git hosting platforms were designed for a specific era: humans writing code, committing it, and reviewing each other’s work. That model is well understood, and it works. But the rise of AI coding agents has quietly exposed a structural problem: the repo is being treated as a System of Action, not just a System of Record.

Watch what happens when you give a conventional AI bot commit access. It creates a branch. It opens a pull request. It responds to review comments by pushing new commits. It’s helpful, but it’s also noisy — and over time, a Git log full of fix(agent): address review comment (attempt 3) commits stops being a reliable record of anything. For teams that depend on a clean, auditable history to understand how a system reached its current state, that pollution is a real cost.

VeloGit was built from the ground up to solve this. Rather than bolting AI onto an existing workflow, we designed the platform around a simple premise: the agent is a collaborator, not a committer. Every architectural decision follows from that.

II. The Data Plane: The Hub for Git and API Traffic

The core of VeloGit is the data-plane, a single Go binary that handles everything a developer touches directly: the REST API, Git Smart HTTP via git http-backend, webhook dispatch, pipeline management, and the registry.

Go was a natural fit for this role. Its concurrency model — lightweight goroutines and channel-based coordination — handles the bursty, IO-heavy nature of Git RPC well. A git push involves receiving a packfile, writing objects to R2 object storage, updating refs, and triggering downstream events, all of which happen concurrently without blocking the HTTP server. In a multi-tenant environment where dozens of organizations share the same process, that isolation matters.

The data-plane exposes two ports:

Port 8081 — the public API and Git Smart HTTP endpoint, protected by Zitadel OIDC tokens for API calls and Personal Access Tokens for Git operations
Port 8082 — an internal API used by the rituals runner and agent service to post results back without going through the public auth layer

Authentication is handled by a Zitadel introspection middleware. Git clone and push use HTTP Basic Auth with PATs stored as SHA-256 hashes. Auth init is fatal — there is no unauthenticated fallback, which keeps the security model simple.

Storage is abstracted behind an ObjectStorage interface backed by Cloudflare R2 in production. Git pack objects, ritual logs, and binary registry artifacts all share the same bucket, separated by key prefix. The interface also supports a local filesystem backend that activates automatically when storage credentials are absent, which makes local development require zero infrastructure beyond a running Postgres and NATS.

III. The Agent Service: The Stateless Overlay

In traditional workflows, bolting on AI usually means handing over commit access to automated bots. This inevitably creates noisy branches, automated pull requests, and pollutes the Git history. For teams that rely on a clean, auditable log to understand system state, this introduces unnecessary friction and diminishes the developer’s control over their own codebase.

To solve this, VeloGit’s Agent Service is built as a standalone, stateless application written entirely in Go. Instead of acting as an active committer, the agent operates through passive observation. It subscribes to platform events, such as a push or pull_request.created, pulls the relevant code, and analyzes the diff.

Rather than spamming the repository with automated commits, the Agent Service generates high-fidelity suggestions known as Shadow Fragments. These fragments are strictly metadata. They contain the proposed diff, the agent’s confidence score, and the specific commit SHA they apply to, but they exist entirely outside of the Git object store.

This architectural boundary is crucial for high-velocity teams. It ensures the Git log remains a pure, unpolluted record of human intent. These suggestions are surfaced in the Ghost Workspace as a side-by-side diff view, where the proposed changes sit alongside the current code for clear, readable review. Developers maintain complete autonomy—they review the diff and simply click “Meld” to apply the verified fix as a human-approved system commit. The machine removes the obstacle of finding the fix, but the engineer remains the ultimate gatekeeper.

IV. The Rituals Engine: Container-Native CI/CD

VeloGit’s CI/CD system is called Rituals. Pipelines are declared in .velo/rituals.yaml alongside your code, and the engine is split across two services.

The rituals-dispatcher runs persistently and subscribes to commit events via NATS JetStream. When a push arrives, it provisions an ephemeral machine on Fly.io — a full VM booted from a base OCI image specified in the yaml — and hands off execution. The machine is torn down when the run finishes or a configurable timeout is reached.

The rituals-service runs inside that ephemeral machine. It clones the repo, executes steps sequentially, and streams log output back to the data-plane’s internal API in real time. Steps marked critical: true abort the run on failure. Steps typed as gate pause execution and notify the team — a human approves or rejects via the UI or the velo pipeline approve CLI command before the next machine boots.

This split matters: the gate approval model means a run that passes build and test can wait up to 48 hours for a human to approve the deploy step, then resume on a fresh machine with a clean environment. There are no long-lived runner processes to maintain.

Running pipelines locally is first-class. The velo run command reads .velo/rituals.yaml from the current directory, pulls the base image, and executes steps inside a local Docker or Podman container with your working tree bind-mounted to /workspace:

# Run the full pipeline
velo run

# Test a single step against your current working tree
velo run --step build

# Resume from a specific step, skip gate prompts
velo run --from deploy-setup --skip-gates

This means the exact same environment that runs in CI can be reproduced locally in under a minute — no “works on my machine” gap between local and remote execution.

V. The Ghost UI: A Desktop-Class Frontend

The frontend is a Vue 3 / Quasar 2 single-page application deployed as a Cloudflare Worker. It communicates with the data-plane exclusively over the REST API, injecting a Bearer token from the OIDC session on every request.

The centrepiece is the Ghost Workspace — a full-screen, side-by-side diff viewer that renders Shadow Fragments alongside the current file contents. Each fragment is rendered as a transparent overlay on the actual code, so the developer sees exactly what would change and in what context. Clicking Meld triggers the data-plane to temp-clone the repository, write the proposed change to disk, commit it as the authenticated developer, and push back to the branch. The agent’s suggestion becomes a human-owned commit with a clean message.

The broader interface covers the full development workflow: pull requests with inline comments, review requests, draft PRs, branch protection rules, @mention notifications, a live pipeline log viewer with per-step status, webhook delivery history, and a binary release registry for distributing build artifacts. It’s built as a dark-mode-first progressive application that works equally well on desktop and mobile.

State is managed with Pinia stores, and the router uses meta guards (requiresAuth, requiresActivation) to redirect unauthenticated users cleanly without flashing protected content.

VI. Conclusion: Own Your Workflow

VeloGit’s architecture makes one strong bet: that the right relationship between AI and a codebase is advisory, not authoritative. Shadow Fragments keep the agent out of the Git object store. Rituals keep pipeline config in the repo, not locked in a SaaS UI. The data-plane is a single auditable Go binary, not a black box.

The entire core is open source. You can read the auth code, inspect how your repositories are stored, and verify that nothing happens behind your back. For teams who need a Git platform they can actually trust — not just one that promises to behave — that auditability is the foundation everything else is built on.

To get started self-hosting or explore the hosted version, see the Introduction and Getting Started guides.