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

# Git Sync

> Sync rollout code and configs from your workspace repository to Osmosis

## Overview

Git Sync connects a platform workspace to a GitHub workspace repository. The platform reads rollout code and configuration from that repository, discovers rollouts under `rollouts/`, and makes them available for training.

Your local workspace directory is a clone of the same repository. Push to the default branch to sync changes.

## Repository Setup

<Steps>
  <Step title="Create or connect a workspace repository">
    Workspace owners and admins connect GitHub in the platform, then create a private workspace repository from the Osmosis workspace template or connect an existing repository.

    New repositories created from the platform include the starter examples `multiply-local-strands`, `multiply-local-openai`, and `multiply-harbor-strands`. For the full first-time setup flow, start with [Onboarding](/platform/onboarding).
  </Step>

  <Step title="Work from the local workspace directory">
    Your local workspace directory should be a clone of the connected GitHub repository. Invited members use the existing workspace repository rather than creating a second one.
  </Step>

  <Step title="Verify local context">
    From your local workspace directory, confirm the `origin` remote points at the connected GitHub repository:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
    git remote get-url origin
    osmosis doctor
    ```
  </Step>
</Steps>

## How Sync Works

* **Pushing to the default branch** triggers an automatic sync.
* The platform discovers rollout definitions in the `rollouts/` directory.
* Each rollout subdirectory (e.g. `rollouts/my-rollout/`) becomes a rollout entity on the platform, available for training and evaluation.
* Config files under `configs/` are also synced so that `osmosis train submit` can reference them by path.
* The platform records sync history with commit SHA, author, message, status, and number of rollouts discovered.

<Warning>
  Git Sync is the source of truth for your rollout code. The CLI reads config values from the local TOML file you pass, but rollout code comes from the synced workspace repository. Commit, push, and wait for sync before submitting code changes; set `commit_sha` when you need a specific synced revision.
</Warning>

## Sync Status

View sync history in the platform under **Git Integration**. Each sync event shows:

| State       | Meaning                                            |
| ----------- | -------------------------------------------------- |
| **Pending** | Push detected, sync queued                         |
| **Syncing** | Platform is processing the repository contents     |
| **Success** | All rollouts synced successfully                   |
| **Failed**  | Sync encountered an error (check logs for details) |

A manual sync action is available in the platform to re-process the current default branch without pushing a new commit.

## Blocking States

The platform shows a banner when GitHub setup blocks training workflows.

| State                   | Effect                                              | Fix                                                 |
| ----------------------- | --------------------------------------------------- | --------------------------------------------------- |
| No GitHub installation  | Rollout sync and training setup cannot proceed.     | Connect GitHub from **Git Integration**.            |
| No repository connected | The platform has no workspace repository to sync.   | Create or connect a workspace repository.           |
| GitHub App disconnected | Training runs are blocked until access is restored. | Reconnect the GitHub App.                           |
| Repository needs setup  | The repository record needs repair or replacement.  | Open **Git Integration** and follow the setup flow. |

## Important Notes

* Only pushes to the default branch trigger automatic sync.
* Pushes to feature branches are ignored until merged into the default branch.
* If the repository is renamed on GitHub, update your local `origin` remote and check the platform connection.

<Tip>
  Use `commit_sha` in your [training config](/cli/config-files#training-config) to pin a training run to a specific commit.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Workspace Repository" icon="code-branch" href="/cli/workspace/repository">
    Learn how local CLI commands are scoped to a repository.
  </Card>

  <Card title="Training Runs" icon="play" href="/platform/training-runs">
    Submit training after Git Sync succeeds.
  </Card>
</CardGroup>