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

# GitHub Sync

> Connect a repository, commit changes, push, and pull — without leaving the workspace.

Botflow has a built-in GitHub integration that lets you version-control your project using a real Git workflow. You connect a repository once; after that, committing, pushing, and pulling are one click away.

## Connecting GitHub

1. Click the **GitHub** button (the octocat icon) in the top-right toolbar.
2. If you haven't connected GitHub yet, you'll be prompted to authorise Botflow via GitHub OAuth. Click the link — you'll be redirected to GitHub and back automatically.
3. After authorising, you'll see a list of your repositories and organisations.
4. Select the repository you want to link to this project.

<Note>
  You can connect a fresh empty repository or an existing one. If you connect an existing repository with files, Botflow clones the default branch into your project's sandbox.
</Note>

## Viewing the status

Once a repository is connected, opening the GitHub panel shows a status summary:

* **Branch** — the current branch name (matches the repository's default branch after connecting)
* **Changed files** — a list of files that have been modified since the last commit (added, modified, deleted)
* **Pending commits** — commits that have been created locally but not yet pushed to GitHub

## Committing changes

1. Open the **GitHub** panel.
2. Review the list of changed files.
3. Type a commit message in the input field.
4. Click **Commit**.

The commit is created and added to the pending-commits list. Your files are unchanged.

## Pushing to GitHub

After creating one or more commits, click **Push** to upload them to GitHub. Botflow runs a real `git push` from inside the sandbox — your OAuth token is injected only for the duration of the push and is never written to disk.

<Tip>
  Push frequently to avoid divergence between your local workspace and the remote. If you're building something significant, push after each logical chunk of work.
</Tip>

## Letting the agent commit for you

The first time you link a repository, the AI agent asks how you'd like commits handled. Your choice is saved per-project, and you can change it any time by telling the agent (e.g. "stop committing automatically").

There are three modes:

| Mode              | What the agent does                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| **Autonomous**    | Commits and pushes on its own after each meaningful change — you don't have to think about Git. |
| **Ask each time** | Pauses and asks for confirmation before every commit, so you stay in control of what lands.     |
| **Manual**        | The agent never touches Git. You commit and push yourself from the GitHub panel.                |

<Tip>
  **Autonomous** pairs well with frequent, low-stakes iteration — every change is captured in history. Switch to **Ask each time** or **Manual** when you're working toward a specific commit and want clean, deliberate history.
</Tip>

## Pulling from GitHub

If the remote branch has new commits (e.g. from a collaborator or from another device), click **Pull** to fetch and merge them.

Botflow uses a real Git merge:

1. It fetches the latest commits from the remote.
2. Any uncommitted local changes are safely set aside as a work-in-progress commit first, so nothing is lost.
3. It merges the remote branch into your working tree.

If the merge is clean, your sandbox files are updated in place. If the same lines changed on both sides, Botflow opens the **Conflict Resolution** dialog.

## Resolving conflicts

When a pull results in conflicting changes (the same file was modified both locally and remotely), the conflict modal lists each conflicted file and asks you to choose how to resolve it:

* **Keep mine** — discard the remote change, keep your local version
* **Use theirs** — discard your local change, apply the remote version
* **Manual** — Botflow applies both sets of changes and you edit the resulting file in the editor

After resolving all conflicts, the pull completes and you can continue working.

## Disconnecting a repository

To unlink the repository from this project, open the GitHub panel and click the **disconnect** option. This does not delete your GitHub repository or your local files — it simply removes the link so the GitHub panel no longer shows push/pull controls.

## Tips

* **One repository per project** — each Botflow project maps to a single GitHub repository (or a single branch of a repository).
* **Real Git under the hood** — the integration runs the actual `git` binary inside your sandbox, so the project has a genuine `.git` directory and full history. You can also use `git` directly from the [terminal](/docs/features/editor#terminal) if you prefer.
* **Large files** — GitHub has a 100 MB file size limit per file. Files larger than that will fail to push. Use [Git LFS](https://git-lfs.com) or keep large assets in cloud storage.
* **Private repos** — fully supported. The OAuth token Botflow stores is scoped to repository read/write access only.
* **Alternative to cloud backup** — GitHub sync provides off-site backup and version history. For critical projects, push frequently or maintain local backups via the [Download](/docs/features/editor#downloading-your-project) button.