> ## 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.

# repos.sync_upstream()

> Enqueue a sync to a repository's configured upstream.

Enqueue a sync for a repository that has an upstream remote.

**Required scope: `write`**

```python theme={null}
sync = await mesa.repos.sync_upstream(repo="app", direction="pull")
print(sync.id, sync.status)

await mesa.repos.sync_upstream(
    repo="app",
    direction="pull",
    ref_globs={
        "branches": "main",
    },
)
```

## Options

<ParamField path="repo" type="str" required>
  Repository name.
</ParamField>

<ParamField path="direction" type="'pull' | 'push'" required>
  `pull` fetches from upstream into Mesa. `push` sends Mesa branches and tags to upstream.
</ParamField>

<ParamField path="ref_globs" type="dict | None">
  Branch and tag glob filters for this sync. Omit this field to sync all supported branches and tags. If provided, include at least one of `branches` or `tags`.
</ParamField>

<ParamField path="ref_globs.branches" type="str">
  Glob matched against upstream branch names, such as `main`, `release/*`, or `*`. Omit or use an empty string to match no branches. Do not include `refs/heads/`.
</ParamField>

<ParamField path="ref_globs.tags" type="str">
  Glob matched against upstream tag names, such as `v1.*` or `*`. Omit or use an empty string to match no tags. Do not include `refs/tags/`.
</ParamField>

<ParamField path="org" type="str | None">
  Organization override.
</ParamField>

## Response

<ResponseField name="id" type="str">
  Sync ID.
</ResponseField>

<ResponseField name="repo_id" type="str">
  Repository ID.
</ResponseField>

<ResponseField name="direction" type="'pull' | 'push'">
  Sync direction.
</ResponseField>

<ResponseField name="status" type="'queued' | 'in_progress' | 'completed' | 'failed'">
  Current sync status.
</ResponseField>

<ResponseField name="attempt" type="int">
  Attempt number for this run.
</ResponseField>

<ResponseField name="ref_globs" type="SyncRefGlobs">
  Branch and tag glob filters for this run.
</ResponseField>

<ResponseField name="stats" type="SyncRunStats | None">
  Per-ref sync stats, or null until the run reaches a terminal state.
</ResponseField>

<ResponseField name="error" type="str | None">
  Failure message, or null when no error is present.
</ResponseField>

<ResponseField name="created_at" type="datetime">
  Creation time.
</ResponseField>

<ResponseField name="started_at" type="datetime | None">
  Start time, or null if the run has not started.
</ResponseField>

<ResponseField name="finished_at" type="datetime | None">
  Finish time, or null if the run has not finished.
</ResponseField>

### SyncRefGlobs

<ResponseField name="branches" type="str">
  Branch-name glob for this sync.
</ResponseField>

<ResponseField name="tags" type="str">
  Tag-name glob for this sync.
</ResponseField>

### SyncRunStats

<ResponseField name="refs" type="list[SyncRunRef]">
  Per-ref sync outcomes. This contains only source refs that matched `ref_globs`.
</ResponseField>

### SyncRunRef

<ResponseField name="name" type="str">
  Git ref name.
</ResponseField>

<ResponseField name="before" type="str | None">
  Previous OID, or null when the ref was newly created.
</ResponseField>

<ResponseField name="after" type="str">
  OID after the sync attempt.
</ResponseField>

<ResponseField name="outcome" type="'updated' | 'unchanged' | 'filtered' | 'rejected'">
  Result for this ref.
</ResponseField>