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

# GitHub Sync

> Connect your Bloom app to GitHub for bidirectional code synchronization.

GitHub Sync connects your Bloom app to a GitHub repository, enabling bidirectional synchronization. Changes you make in Bloom automatically push to GitHub, and changes pushed to GitHub sync back to Bloom.

<Info>
  GitHub Sync is currently in **beta** and available on **Premium plans and above**.
</Info>

## Setting Up GitHub Sync

In the top right corner of the editor, click the **GitHub Sync** button.

<Frame>
  <img src="https://mintcdn.com/bloom-eafef039/6Jj6W1TQ2_0nANBi/images/github-sync.png?fit=max&auto=format&n=6Jj6W1TQ2_0nANBi&q=85&s=41f0095bc097c8473197f47d7fc9d89c" alt="GitHub Sync" width="1115" height="1347" data-path="images/github-sync.png" />
</Frame>

<Steps>
  <Step title="Create a new empty repository on GitHub">
    Click **Create New Repository** to open GitHub directly. The repository must be empty for the initial sync to work correctly.
  </Step>

  <Step title="Install the GitHub App">
    Click **Install GitHub App** to install the Bloom GitHub App and grant it access to your repository. You can grant access to all repositories or only select repositories.
  </Step>

  <Step title="Enter your repository name">
    Enter your repository name in the format `username/repository` or `organization/repository`, then click **Configure**.

    You can also click **Browse Available Repositories** to select from repositories you've already granted access to.
  </Step>
</Steps>

Once connected, your app's code will sync to the repository automatically.

## How Sync Works

GitHub Sync maintains bidirectional synchronization between Bloom and your repository.

<Tabs>
  <Tab title="Bloom → GitHub">
    **Changes made in Bloom push to GitHub automatically.**

    When you generate new features or make any changes in Bloom, those changes are committed and pushed to your connected repository.

    * Each generation creates a new commit
    * Commits include descriptive messages
    * Your full commit history is preserved
  </Tab>

  <Tab title="GitHub → Bloom">
    **Changes pushed to GitHub sync back to Bloom.**

    When you push commits to your repository (from your local IDE, GitHub's web editor, or any Git client), those changes automatically sync back to your Bloom app.

    * Pull the latest changes by refreshing your Bloom workspace
    * Merge conflicts are handled automatically when possible
    * You'll be notified if manual resolution is needed
  </Tab>
</Tabs>

## Use Cases

<CardGroup cols={2}>
  <Card title="Work in Your IDE" icon="code">
    Use VS Code, Cursor, or any editor you prefer. Push changes to GitHub and they'll appear in Bloom.
  </Card>

  <Card title="Team Collaboration" icon="users">
    Multiple team members can work on the same app using standard Git workflows.
  </Card>

  <Card title="Version Control" icon="clock-rotate-left">
    Full Git history lets you track changes, revert mistakes, and understand how your app evolved.
  </Card>

  <Card title="CI/CD Integration" icon="rotate">
    Connect your repo to GitHub Actions or other CI/CD tools for automated testing and deployment.
  </Card>
</CardGroup>

## Working Locally

Once your app is synced to GitHub, you can clone it and run it locally.

### Prerequisites

* **Bun** (JavaScript runtime and package manager)
* **Convex CLI** (for running the backend)

### Running Your App

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    git clone https://github.com/your-username/your-app.git
    cd your-app
    bun install
    ```
  </Step>

  <Step title="Set up environment variables">
    Copy the example environment file and fill in your Convex deployment details:

    ```bash theme={null}
    cp .env.example .env
    ```

    You can find your Convex deployment URL in your [**Convex dashboard**](https://dashboard.convex.dev).
  </Step>

  <Step title="Start the development server">
    ```bash theme={null}
    bun run dev
    ```

    This starts both the Expo frontend and Convex backend.
  </Step>
</Steps>

<Note>
  See [**App Structure**](/app-structure) to understand how your project files are organized.
</Note>

## Requirements and Limitations

<AccordionGroup>
  <Accordion title="Plan requirements" icon="credit-card">
    GitHub Sync is available on **Premium plans and above** (\$50/month).

    [**View pricing →**](https://bloom.diy/pricing)
  </Accordion>

  <Accordion title="Repository requirements" icon="folder">
    * The repository must be **empty** when you first connect
    * You must have **write access** to the repository
    * The Bloom GitHub App must be installed and authorized
  </Accordion>

  <Accordion title="Beta limitations" icon="flask">
    GitHub Sync is currently in beta. You may encounter:

    * Occasional sync delays
    * Edge cases with complex merge conflicts

    Report any issues to [**support@bloom.diy**](mailto:support@bloom.diy) or in our [**Discord**](https://discord.com/invite/ZC3zgARtUY).
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="App Structure" icon="folder-tree" href="/app-structure">
    Understand how your synced codebase is organized
  </Card>

  <Card title="Backend Dashboard" icon="chart-line" href="/backend-dashboard">
    Monitor your app's performance and database
  </Card>
</CardGroup>