# Set up two-way sync

> For the complete documentation index, see [llms.txt](https://falconer.com/docs/llms.txt).

Connect a space to a GitHub repository and import its docs.


Connect a space to a GitHub repository and import its docs.

## Prerequisites

- **The GitHub App is connected to your organization.** An organization admin connects it from **Integrations**. See [GitHub](https://falconer.com/docs/integrations/github.md). Repositories added as public repositories, without the GitHub App, are read-only and can't be synced.
- **You've connected your personal GitHub account.** Falconer uses it to author your commits and pull requests. Connect it from **Settings > Personal > Connected accounts**, or click **Connect GitHub** when Falconer asks.
- **You have edit access to the space.**

## Which spaces can sync

Two-way sync is set up on a [space](https://falconer.com/docs/organize/spaces.md), not on a regular folder.

A space can't be synced if it contains a synced space or sits inside one.

## Connect a space

1. Open the space and choose **Sync with GitHub** from its **More actions** menu.

   You can also turn on **Sync with GitHub** when you create a new space, or click **Sync with GitHub** in an empty space.

2. Pick a repository from **Connected repositories**.

3. Choose where to sync:

   - **Base path:** the directory in the repository that holds your docs. Leave it at the repository root to sync everything.
   - **Branch:** the branch to sync with. To start from a new branch, type its name and choose **Create branch**.
   - **Merge strategy:** how your pushes reach GitHub. See [Choose a merge strategy](#choose-a-merge-strategy).

4. Review the summary and click **Start sync**.

The import runs in the background. When it finishes, click **View documents** to open the synced space.

## Choose a merge strategy

| Merge strategy | What a push does |
| --- | --- |
| **Direct commit** | Commits straight to the synced branch. |
| **Pull request** | Opens a GitHub pull request against the synced branch, or updates an open one. |

You can change the merge strategy later from the space's sync settings. See [Manage or disconnect sync](https://falconer.com/docs/two-way-sync/manage-sync.md).

## What gets imported

- `.md` and `.mdx` files become documents, and directories become folders.
- Images and other files are listed in the **Files** tab. See [Images and other files](https://falconer.com/docs/two-way-sync/images-and-files.md).
- Markdown inside `node_modules` and build output directories such as `dist`, `build`, and `.next` isn't imported as documents. Every tracked file still appears in the **Files** tab and counts toward the [size limits](https://falconer.com/docs/two-way-sync/images-and-files.md#size-limits), so if your repository commits generated output, choose a narrower base path.

If the import doesn't finish, the space header shows **Import failed**. Open the GitHub sync drawer and click **Retry import** in the **Issues** tab.

## Sync several branches or paths of one repository

More than one space can sync the same repository. Each space needs its own branch, or a path on the same branch that doesn't overlap another space's.

Branches that would overlap an existing sync are disabled in the branch picker and show which space they're synced to.