GitHub

Attach an upstream Git repository to a Mesa repository and trigger syncs with syncUpstream. Syncs report their progress through sync.* webhook events and are exposed on the repository’s upstream field. The upstream is per-repository configuration: one Mesa repo points at one upstream URL, with optional stored credentials. The upstream can be GitHub, GitLab, Bitbucket, or any Git server that supports the Git HTTPS smart protocol.

Sync semantics

By default, Mesa’s GitHub sync is conservative, and will only update branches and tags that have not diverged (fast-forward only). Deletions are not synced. This behavior is the same both when pulling upstream changes and when pushing Mesa changes to an upstream. Mesa attempts to sync all branches and tags by default. You can also filter branches and tags for a single sync with glob patterns. If some matching branches and tags cannot be safely updated (non-fast-forward, branch protection rules, etc.), those updates will be skipped without failing the entire sync. Once a sync completes, per-ref sync outcomes are surfaced in the sync’s stats field.

Configure an upstream

Set an upstream when creating the repository, or attach one later with mesa.repos.update(...). The auth payload is write-only — Mesa stores credentials securely and only returns the auth_kind on read. Repository responses include upstream.latest_sync, which is null until the first sync is enqueued.

import { Mesa } from "@mesadev/sdk";

const mesa = new Mesa({ apiKey: process.env.MESA_API_KEY });

await mesa.repos.update({
  repo: "app",
  upstream: {
    url: "https://github.com/acme/app.git",
    auth: {
      kind: "token",
      token: process.env.GITHUB_PAT!,
      token_username: "x-access-token",
    },
  },
});

from mesa_sdk import Mesa
from mesa_sdk.types import TokenAuth, UpstreamConfig

mesa = Mesa()

await mesa.repos.update(
    repo="app",
    upstream=UpstreamConfig(
        url="https://github.com/acme/app.git",
        auth=TokenAuth(
            token=os.environ["GITHUB_PAT"],
            token_username="x-access-token",
        ),
    ),
)

Auth options

`auth.kind`	When to use
`token`	A GitHub personal access token (`github_pat_...`) or other single-token credential. `token_username` is optional; most Git servers will accept basic auth with an arbitrary username. One notable exception is BitBucket, which expects the token owner’s username.
`username_password`	Classic username/password basic auth. Use for self-hosted Git servers or providers that do not issue tokens.
(omitted)	Public upstream. Reads work without auth; pushes will fail.

On repos.update(...), omitting a value for upstream auth preserves the stored credential, while passing null/None clears the stored credential:

Value	Behavior
Omitted	Preserve the stored credential.
`null` (TS) / `None` (Python)	Clear the stored credential. The upstream becomes public.
`{ kind: ..., ... }` / `TokenAuth` / `UsernamePasswordAuth`	Replace the stored credential.

Trigger a sync

syncUpstream({ direction: "pull" }) fetches branches and tags from the upstream repository and applies any safe updates to the Mesa repository. direction: "push" works the same way in the other direction; branches and tags are fetched from your Mesa repository, and any safe updates are applied to the upstream repo. Omit ref_globs or use { branches: "*", tags: "*" } to sync all supported branches and tags. To sync only selected refs, pass branch and tag glob filters. If you provide ref_globs, include at least one of branches or tags; an omitted namespace matches no refs. Branches and tags are plain names such as main, release/*, or v1.*, not fully-qualified Git refs such as refs/heads/main. This method enqueues a sync job and returns an object containing the id of the queued sync. The work is performed asynchronously. Fetch the repository and read repo.upstream.latest_sync, fetch the sync by id, or list the repository’s upstream sync history to check status.

// Pull upstream changes into Mesa
const sync = await mesa.repos.syncUpstream({ repo: "app", direction: "pull" });
console.log(sync.id, sync.status); // "sync_...", "queued"

// Or pull only matching branches and tags
await mesa.repos.syncUpstream({
  repo: "app",
  direction: "pull",
  ref_globs: {
    branches: "main",
  },
});

// Or push Mesa changes to the upstream
await mesa.repos.syncUpstream({ repo: "app", direction: "push" });

# Pull upstream changes into Mesa
sync = await mesa.repos.sync_upstream(repo="app", direction="pull")
print(sync.id, sync.status)  # "sync_...", "queued"

# Or pull only matching branches and tags
await mesa.repos.sync_upstream(
    repo="app",
    direction="pull",
    ref_globs={
        "branches": "main",
    },
)

# Or push Mesa changes to the upstream
await mesa.repos.sync_upstream(repo="app", direction="push")

// See the latest sync status on the repo object
const repo = await mesa.repos.get({ repo: "app" });
console.log(repo.upstream?.latest_sync?.status, repo.upstream?.latest_sync?.stats);

// Or fetch the status of a specific sync
const sync = await mesa.repos.getUpstreamSync({ repo: "app", syncId: "sync_..." });
console.log(sync.status, sync.stats);

// Or list the sync history for a repo
const { syncs } = await mesa.repos.listUpstreamSyncs({ repo: "app", limit: 20 });
for (const sync of syncs) {
  console.log(sync.direction, sync.status, sync.created_at);
}

# See the latest sync status on the repo object
repo = await mesa.repos.get(repo="app")
print(repo.upstream.latest_sync.status if repo.upstream and repo.upstream.latest_sync else None)

# Or fetch the status of a specific sync
sync = await mesa.repos.get_upstream_sync(repo="app", sync_id="sync_...")
print(sync.status, sync.stats)

# Or list the sync history for a repo
result = await mesa.repos.list_upstream_syncs(repo="app", limit=20)
for sync in result.syncs:
    print(sync.direction, sync.status, sync.created_at)

status transitions through queued → in_progress → completed or failed. Once a sync completes, a stats field becomes available with per-ref outcomes (updated, unchanged, filtered, or rejected). stats.refs includes only matching source branches and tags. If a sync fails, the error field provides a failure reason. Syncs emit four webhook event types over their lifecycle. Subscribe on a webhook target to drive your own workflows without polling.

Event	Fires when
`sync.queued`	A `syncUpstream` call enqueues a new sync.
`sync.in_progress`	The worker picks up the sync.
`sync.completed`	The sync finishes with terminal status `completed`.
`sync.failed`	The sync finishes with terminal status `failed`. The payload includes `error`.

const target = await mesa.webhookTargets.create({
  url: "https://acme.dev/webhooks/mesa",
  events: ["sync.completed", "sync.failed"],
  repo_ids: ["repo_abc123"],
});

Pull syncs also cause the repo.push webhook event to fire if upstream changes are received by Mesa. See Webhooks for delivery semantics, signature verification, and the full event payload shape.

Required scopes

Operation	Scope
Attach or update upstream config	`write` on the repository
Sync upstream	`write` on the repository
Read sync history	`read` on the repository

REST endpoints

Each SDK method maps to a REST endpoint under the organization root:

Method	Endpoint
Configure upstream	`POST /v1/:org/repos` and `PATCH /v1/:org/:repo`
Sync upstream	`POST /v1/:org/:repo/upstream/syncs`
Get upstream sync	`GET /v1/:org/:repo/upstream/syncs/:syncId`
List upstream syncs	`GET /v1/:org/:repo/upstream/syncs`

See the REST API reference for full request and response schemas.

Getting Started

Concepts

MesaFS

Usage Patterns

Integrations

Sync semantics

Configure an upstream

Auth options

Trigger a sync

Required scopes

REST endpoints

​Sync semantics

​Configure an upstream

​Auth options

​Trigger a sync

​Subscribe to sync events

​Required scopes

​REST endpoints

Sync semantics

Configure an upstream

Auth options

Trigger a sync

Subscribe to sync events

Required scopes

REST endpoints