GitHub sync

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

What GitHub sync is for

Use GitHub sync when your docs, specs, notes, or internal knowledge already live in a repository and you want Open Knowledge to keep that repository up to date automatically.

It helps you:

• Start from an existing GitHub repository
• Keep your knowledge base in sync with updates from your team
• Resolve conflicts between your edits and your team's edits

Clone from the app

In the app, the Clone from GitHub card opens a clone dialog for interactive setup.

Enable sync after cloning

When you open a freshly cloned project, GitHub sync is off by default. Toggle it on from the project settings page once you are ready for Open Knowledge to start writing commits to the remote.

While sync is active, Open Knowledge:

• Fetches and pulls commits from the remote on a regular cadence
• 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

Private repositories require GitHub authentication. If you are logged in with the GitHub CLI, Open Knowledge will use those credentials. If not, you can complete device authentication to generate an OAuth token. Open Knowledge stores this token in the keychain and reuses it for each sync.

Manage the connection from Settings → Account. Connect GitHub authorizes Open Knowledge to browse and sync your repositories; Disconnect removes the credential Open Knowledge stored. Disconnecting clears Open Knowledge's own token only; repositories you have already cloned may keep syncing with credentials Git itself saved.

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.