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.
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.
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",
},
},
});
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. |
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" });
// 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);
}
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.
Subscribe to sync events
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"],
});
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 |
