Overview - Mesa Docs

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)

Both plain and gzip-compressed request bodies are accepted.

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

API keys can be org-wide or scoped to specific repositories. See Authentication for details.

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.

macOS
Linux
Windows

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

The 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

These limits apply to individual push operations. There are no rate limits on the number of operations.

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

When you 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.

​Base URL

​Endpoints

​Authentication

​Scopes

​Clone and fetch

​Push

​Branch operations

​Credential helpers

​CI/CD example

​Supported operations

​Wire protocol

​Client compatibility

​Supported fetch arguments

​Limits

​Git ↔ Mesa concept mapping

Base URL

Endpoints

Authentication

Scopes

Clone and fetch

Push

Branch operations

Credential helpers

CI/CD example

Supported operations

Wire protocol

Client compatibility

Supported `fetch` arguments

Limits

Git ↔ Mesa concept mapping