---
title: GitHub sync
icon: custom/GitHub
description: Clone repos from GitHub, auto-sync changes with your team, and resolve conflicts.
---
OpenKnowledge can connect a project to a GitHub remote repository and keep it synced over time. When GitHub sync is enabled, OpenKnowledge actively pulls commits from the remote and pushes commits back.

<Callout type="warn">
  Only enable GitHub sync for repositories where you are comfortable with OpenKnowledge writing commits to the remote history. If you are worried about automated commits corrupting or cluttering your Git history, do not enable sync for that repository.
</Callout>

## What GitHub sync is for

Use GitHub sync when you want to collaborate with your team on an OpenKnowledge project.

It helps you:

- Keep your project in sync with updates from your team
- Resolve conflicts between your edits and your team's edits

## Clone an existing GitHub repository

<Steps>

<Step>
    ### Open the clone dialog

    From the Navigator window, click **Clone from GitHub**. You can open the navigator window from the editor by clicking on your project name in the bottom left and then clicking **Switch project**.
</Step>

<Step>
    ### Sign into GitHub

    If you are already signed in with the GitHub CLI, OpenKnowledge will use those credentials by default. If not, click **Sign into GitHub** and complete the device authentication flow.
</Step>

<Step>
    ### Choose a repository

    Paste a repository URL or `owner/repo` shorthand. You can also filter and select from a list of repositories your account can access.
</Step>

<Step>
    ### Open the project

    When the clone completes, the cloned project opens in a new editor window and the Navigator closes. Re-summon the Navigator from inside the editor via the sidebar Switch Project pill, the File menu, or the Command Palette.
</Step>
</Steps>

## Publish a local project

You can publish your local project to GitHub directly from the OpenKnowledge app by opening a folder or file and clicking the **Share** button in the top right of the editor.

This will open a dialog where you can choose an owner and repository name. You can also choose to make the repository public or private.

## Enable GitHub sync

When you open a freshly cloned project, you will be prompted to enable sync. You can also toggle it from the project settings page at any time.

While sync is active, OpenKnowledge:

- Fetches commits from the remote
- Commits your edits locally using the configured Git identity
- Pushes those commits back to the remote so collaborators see your changes

Pulls can overwrite uncommitted local file changes, so commit or discard work-in-progress before you enable sync.

If you want to set a default auto-sync setting for future collaborators, go to the project settings page and navigate to the **Sync** -> **Shared default** section.

## Authentication

If you are logged in with the GitHub CLI, OpenKnowledge will use those credentials for GitHub operations. If not, you can complete device authentication to generate an OAuth token. OpenKnowledge stores this token in the keychain and reuses it for syncing, cloning, and publishing.

Manage the connection from **Settings → Account**. **Connect GitHub** authorizes OpenKnowledge to browse and sync your repositories; **Disconnect** clears OpenKnowledge's GitHub token only.

The sync status indicator surfaces an auth-error state when stored credentials stop working, and sync pauses until you reconnect.

## Sync status and conflicts

The sync status indicator in the editor shows the current state of the connection: how many commits you are ahead or behind the remote, when the last sync ran, whether sync is paused, and how many files have unresolved conflicts. You can also trigger an immediate sync from the same control instead of waiting for the next scheduled run.

## Resolving a conflict

When a remote update conflicts with your local edits, OpenKnowledge surfaces the conflict in three places at once: the conflicted file gains a `⚠` badge on its tab, a pinned **Conflicts** section appears at the top of the file tree listing every conflicted file, and the editor area swaps from the normal editor to a unified diff view.

Click the badged tab or any row in the Conflicts section to focus the conflict.

You can't edit a page with conflicts until they're resolved; the same applies to agents writing over MCP.

## Common failure modes

A few situations stop sync from completing successfully. In each case the sync status indicator changes color and tells you what's wrong. Sync stays paused until the underlying issue is fixed, then picks back up on its own.

### Conflicts and pending changes

- **Unresolved conflicts.** If even one file has a conflict between your edits and your team's, sync waits. You can keep working on every other doc; only the conflicted files are frozen until you choose a side from the diff view. See [Resolving a conflict](#resolving-a-conflict) above.
- **Local changes would be overwritten by an incoming update.** A teammate's update is ready to pull, but you have uncommitted local edits to the same file. Sync pauses rather than clobber your work. Commit or discard the in-progress edit from the editor's git surface and sync resumes.
- **Edits made outside the app aren't ready yet.** If you (or another tool) edited a file directly on disk while sync wanted to merge, OpenKnowledge waits until those external edits settle before merging. Usually this clears in a second or two on its own.

### Project isn't on a normal branch

- **The project is parked on a specific commit, not a branch.** This usually means someone checked out an older commit from the terminal to look around. There's no branch to push to, so sync pauses. Switch back to your normal branch (`main`, your working branch, whichever) and sync resumes.
- **Diverged history.** When the remote has been rewritten (force-push, rebase, branch reset) in a way OpenKnowledge can't reconcile automatically, sync stops and shows the error. This one usually needs a fix from the command line. Ask whoever rewrote the history, or restore from the [Timeline](/docs/features/timeline-and-recovery).

### GitHub-side blockers

- **Authentication errors.** Your stored credentials expired, were revoked, or don't have access to this repository anymore. Reconnect from the sync indicator (or from **Settings → Account**) to clear the error.
- **You don't have permission to push to this repo.** Someone shared a project backed by a GitHub repo where your account isn't a collaborator (or has read-only access on a private repo). OpenKnowledge checks this up front: instead of prompting you to enable sync that would just fail, the toggle is disabled with an inline "You don't have permission to push to this repo" message in both the sync indicator popover and **Settings → Sync**. If you had sync enabled on a different repo and switch to one you can't push to, OpenKnowledge pauses sync in-memory rather than mutating your preference; your `Auto-sync: on` setting is preserved for the next repo you have full access to. Ask the project owner for write access, then click sync to re-check.
- **Protected branches and rejected pushes.** If the target branch requires reviews, signed commits, or status checks, GitHub rejects the push. OpenKnowledge turns sync off automatically so it stops retrying. Switch to a branch you can push to, or use a pull request for the protected branch instead.
- **Missing Git identity.** Commits need a name and email attached. The status indicator prompts you to set one the first time sync needs to commit.

### Temporary problems

- **Network or service hiccups.** Flaky Wi-Fi, a VPN drop, or a brief GitHub outage. OpenKnowledge keeps retrying in the background; no action needed unless the issue lasts long enough that you want to manually trigger a sync from the indicator.

