Mesa implements the Git HTTP smart protocol over HTTPS.
Any standard Git client can clone, fetch, and push to Mesa repositories.
Base URL
https://api.mesa.dev/<org>/<repo>.git
| Component | Description | Example |
|---|
<org> | Organization slug | acme |
<repo> | Repository name | agent-workspace |
Endpoints
| Endpoint | Method | Purpose |
|---|
/<org>/<repo>.git/info/refs?service=git-upload-pack | GET | Ref advertisement for fetch/clone |
/<org>/<repo>.git/info/refs?service=git-receive-pack | GET | Ref advertisement for push |
/<org>/<repo>.git/git-upload-pack | POST | Fetch and clone (server sends objects to client) |
/<org>/<repo>.git/git-receive-pack | POST | Push (client sends objects to server) |
Authentication
All endpoints require HTTP Basic auth with a Mesa API key. The username field is ignored — only the password (API key) matters.
https://t:<api-key>@api.mesa.dev/<org>/<repo>.git
t is a conventional placeholder. Any username value works.
Scopes
| Scope | Allowed operations |
|---|
read | git-upload-pack (clone, fetch) |
write | git-upload-pack + git-receive-pack (clone, fetch, push) |
admin | All operations |
Clone and fetch
# Clone with API key embedded in the URL
git clone https://t:mesa_live_xxx@api.mesa.dev/acme/agent-workspace.git
# Use an environment variable (recommended)
git clone https://t:${MESA_API_KEY}@api.mesa.dev/acme/agent-workspace.git
# Fetch latest refs
git fetch origin
Push
Pushing requires the write scope on your API key.
git add .
git commit -m "Add agent prompt"
git push origin main
Branch operations
# Create and push a branch
git checkout -b feature/new-flow
git push -u origin feature/new-flow
# List remote branches
git branch -r
# Delete a remote branch
git push origin --delete feature/old-flow
Credential helpers
Store your Mesa credentials so you don’t need to embed API keys in URLs.
git config --global credential.helper osxkeychain
git clone https://api.mesa.dev/acme/agent-workspace.git
# Username: t
# Password: (your API key)
# Cache credentials in memory for an hour
git config --global credential.helper 'cache --timeout=3600'
# Or store permanently (less secure)
git config --global credential.helper store
git config --global credential.helper manager
CI/CD example
name: Sync to Mesa
on:
push:
branches: [main]
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Push to Mesa
env:
MESA_API_KEY: ${{ secrets.MESA_API_KEY }}
run: |
git remote add mesa https://${MESA_API_KEY}@api.mesa.dev/acme/agent-workspace.git
git push mesa main
Store your API key as MESA_API_KEY in your CI secrets store. Keys without write scope can still clone and fetch.
Supported operations
| Operation | Supported | Notes |
|---|
| Clone | Yes | Full clone via git-upload-pack |
| Fetch / Pull | Yes | Incremental fetching with multi-ack negotiation |
| Push | Yes | Create, update, and delete branches |
| Force push | Yes | Non-fast-forward updates when forced |
| Signed commits | Yes | GPG-signed commits round-trip with stable OIDs |
| Tags | No | Tag pushes are rejected — use bookmarks instead |
Wire protocol
Fetch (upload-pack) speaks Git protocol v2 only. Every info/refs?service=git-upload-pack response advertises:
version 2
agent=mesa/<version>
ls-refs=unborn peel
fetch=wait-for-done shallow ref-in-want
server-option
session-id=<uuid>
object-format=sha1
Git-Protocol request header is ignored — Mesa always responds with v2 on the fetch path. Pre-v2 clients cannot fetch from Mesa.
Push (receive-pack) has no v2 spec upstream and uses the historical smart-HTTP framing. Advertised capabilities: report-status, side-band-64k, ofs-delta, delete-refs.
Client compatibility
| Git client version | Status |
|---|
| Git ≥ 2.26 | Fully supported (v2 is the default since 2.26) |
| Git 2.18 – 2.25 | Supported with git -c protocol.version=2 ... or git config --global protocol.version 2 |
| Git < 2.18 | Not supported — these versions don’t speak v2 |
| libgit2 / JGit / go-git / etc. | Must use a build that speaks v2 |
Supported fetch arguments
Mesa’s v2 command=fetch accepts the baseline gitprotocol-v2 arguments: want <oid>, have <oid>, done, thin-pack, no-progress, ofs-delta, include-tag, and wait-for-done.
Shallow fetch (advertised via fetch=… shallow) is supported: shallow <oid>, deepen <n>, deepen-since <unix-time>, and deepen-relative. The server replies with a shallow-info section listing shallow <oid> / unshallow <oid> boundary changes before the packfile. This powers git clone --depth=<n>, git clone --shallow-since=<date>, git fetch --deepen=<n>, and git fetch --unshallow. deepen-not (--shallow-exclude) is not yet supported.
Ref-in-want (advertised via fetch=… ref-in-want) is supported: want-ref <ref> resolves a ref name to its current oid server-side and reports the result in a wanted-refs section. Because the name is resolved at fetch time, it is immune to the race where a ref moves between a client’s ls-refs and its fetch.
Object filtering (filter) and multi-round negotiation (acknowledgments/ready) are not yet supported.
Limits
| Resource | Limit |
|---|
| Max pack size per push | 5 GiB |
| Max commands per push | 10,000 |
Git ↔ Mesa concept mapping
When you interact with Mesa via Git, concepts are translated automatically:
| Git | Mesa | Notes |
|---|
| Commit | Change | Immutable unit of work with a unique ID |
| Branch | Bookmark | Lightweight, movable pointer to a change |
| Tag | — | Not supported; use bookmarks |
| Staging area | — | No staging; edits go directly to the working change |
git push, commits become changes and branch refs become bookmarks. When you
git clone or git fetch, Mesa translates changes and bookmarks back into commits and refs.
The round-trip is transparent — your Git client sees a normal repository.
See Versioning for a deeper look at changes, bookmarks, and how
Mesa’s model compares to Git and Jujutsu. 
