GitHub sync

Open Knowledge can connect a project to a GitHub remote repository and keep it synced over time. When GitHub sync is enabled, Open Knowledge actively pulls commits from the remote and pushes commits back.

What GitHub sync is for

Use GitHub sync when you want to collaborate with your team on an Open Knowledge 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

Publish a local project

You can publish your local project to GitHub directly from the Open Knowledge 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, Open Knowledge:

• 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.

Authentication

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

Manage the connection from Settings → Account. Connect GitHub authorizes Open Knowledge to browse and sync your repositories; Disconnect clears Open Knowledge'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, Open Knowledge 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 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, Open Knowledge 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 Open Knowledge 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.

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). Open Knowledge 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, Open Knowledge 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. Open Knowledge 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. Open Knowledge 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.