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

# GitHub Integration

> Auto-sync your VibeFlow projects to GitHub repositories

Keep your VibeFlow projects backed up and version-controlled by connecting them to GitHub. Push changes to a repo, pull updates made externally, and optionally auto-push after every agent run.

## Prerequisites

* A VibeFlow paid plan (GitHub sync is a paid feature)
* A GitHub account

## Connecting Your GitHub Account

Before you can sync projects, you need to link your GitHub account to VibeFlow.

<Steps>
  <Step title="Open GitHub settings">
    Go to **Settings > GitHub**. You'll see a **Version Control** card showing your current connection status.
  </Step>

  <Step title="Connect your account">
    Click **Connect**. You'll be redirected to GitHub to authorize VibeFlow. Once complete, the card shows **Active** along with your GitHub username.
  </Step>
</Steps>

To disconnect your account later, click **Disconnect** on the same card.

## Importing a Repository

You can import an existing GitHub repository into VibeFlow as a new project.

<Steps>
  <Step title="Go to Import">
    From the landing page, click **Connect GitHub Repository**, or navigate directly to the import page. If your account isn't linked yet, you'll be prompted to connect first.
  </Step>

  <Step title="Select a repository">
    VibeFlow lists your repositories and checks each one for compatibility (React, Vite, TypeScript). Compatible repos are highlighted. Use the search bar to filter by name.
  </Step>

  <Step title="Set up and open">
    Click a repository to import it. VibeFlow provisions a Convex backend, fetches your files, and opens the project in the editor.
  </Step>
</Steps>

## Syncing a Project to GitHub

Once your GitHub account is connected, you can link any open project to a repository directly from the editor toolbar.

### Connecting a Project

<Steps>
  <Step title="Click the GitHub icon">
    In the editor top bar, click the **GitHub icon**. A **Connect GitHub Repository** dialog opens.
  </Step>

  <Step title="Choose a repository name">
    Enter a name for the new repo (or click the dice icon to generate a random one). The repo is created as **private** under your GitHub account.
  </Step>

  <Step title="Set the branch">
    The default branch is `main`. Change it if you prefer a different branch name.
  </Step>

  <Step title="Create & Connect">
    Click **Create & Connect**. VibeFlow creates the repository and automatically pushes your current project files as the initial commit.
  </Step>
</Steps>

### Pushing Changes

1. Click the **GitHub icon** in the top bar to open the sync popover.
2. Click **Push Latest Changes**.
3. Enter a commit message (a timestamped message is pre-filled) and click **Push**.

If nothing has changed since your last push, VibeFlow lets you know the repo is already up to date.

### Pulling Changes

If commits are made outside VibeFlow (for example, by editing files directly on GitHub or from another tool), a blue dot appears on the GitHub icon to indicate new changes are available.

1. Open the sync popover.
2. Click **Pull Latest Changes**.

VibeFlow fetches the latest files and updates your project in the editor.

### Auto-Push After Agent Runs

When **Auto-push after agent** is enabled (it is by default), VibeFlow automatically pushes your project to GitHub every time the Vibe Agent finishes a task. You can toggle this setting on or off in the sync popover.

### Disconnecting a Project

To unlink a project from its GitHub repo, open the sync popover and click **Disconnect**. This removes the link but does not delete the repository on GitHub.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Does VibeFlow create public or private repositories?">
    All repositories created through VibeFlow are **private** by default.
  </Accordion>

  <Accordion title="Can I connect to an existing repository instead of creating a new one?">
    To work with an existing repo, use the **Import from GitHub** flow on the landing page. The in-editor sync feature creates a new repo for each project.
  </Accordion>

  <Accordion title="What happens if I disconnect a project from GitHub?">
    The link between VibeFlow and the repo is removed. Your code stays in both places; nothing is deleted on either side.
  </Accordion>

  <Accordion title="Do I need a paid plan?">
    Yes. GitHub sync is available on paid plans. Free users see a prompt to subscribe when they click the GitHub icon.
  </Accordion>
</AccordionGroup>