> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Protocol details, endpoints, authentication, capabilities, and limits for Mesa's Git HTTP server.

Mesa implements the [Git HTTP smart protocol](https://git-scm.com/docs/http-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
```

<Tip>
  `t` is a conventional placeholder. Any username value works.
</Tip>

### 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](/content/concepts/authentication) for details.

## Clone and fetch

```bash theme={null}
# 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.

```bash theme={null}
git add .
git commit -m "Add agent prompt"
git push origin main
```

## Branch operations

```bash theme={null}
# 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.

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    git config --global credential.helper osxkeychain
    git clone https://api.mesa.dev/acme/agent-workspace.git
    # Username: t
    # Password: (your API key)
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    git config --global credential.helper manager
    ```
  </Tab>
</Tabs>

## CI/CD example

```yaml theme={null}
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
```

<Tip>
  Store your API key as `MESA_API_KEY` in your CI secrets store. Keys without `write` scope can still clone and fetch.
</Tip>

## 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](/content/concepts/versioning#bookmarks) instead |

## Wire protocol

**Fetch (upload-pack)** speaks **Git protocol v2 only**. Every `info/refs?service=git-upload-pack` response advertises:

```text theme={null}
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](/content/concepts/versioning) for a deeper look at changes, bookmarks, and how
Mesa's model compares to Git and Jujutsu.