Saltar al contenido principal

How sync works

Once a repo is connected, two events bridge Docsio and GitHub:

Publish (Docsio → GitHub)

You edit pages in the Docsio editor. They stay in draft until you click Publish. When you publish:

  1. Docsio diffs your current editor state against the last commit it knows about.
  2. Changed files get committed to your branch as one atomic commit, signed docsio[bot], message prefixed [docsio].
  3. The build runs against the new commit.
  4. Site deploys.

Edits between publishes don't commit. The agent can write 50 files; nothing hits git until you say "Publish."

Push (GitHub → Docsio)

Someone (you, a teammate, or you yourself in your IDE) pushes to your configured branch. GitHub fires a webhook to Docsio. We:

  1. Verify it wasn't a Docsio commit echoing back (three-layer check: author, message prefix, SHA match).
  2. Snapshot your current editor state to your version history (so unpublished editor changes don't get lost).
  3. Pull the diff into your project files.
  4. Trigger a build.

Site is live with the new content within ~60 seconds.

What happens if both happen at once

If you have unpublished editor changes AND a teammate pushes to git at the same time, two things matter:

  1. No data loss. Your editor draft is snapshotted before the pull is applied. Recoverable from version history (Pro) or the editor banner that appears (Free + Pro).
  2. Last write wins per file. If both you and the git push edited the same file, the git push's version is what you'll see in the editor. Your editor version stays in the snapshot.

A banner appears in the editor: "GitHub push from [author] received — your unpublished draft was preserved." with a View saved draft button to restore your version.

Self-commit detection

Docsio's own publish-time commits trigger a webhook just like any other push. We detect ours and skip the pull, so the system doesn't loop.

Three independent checks — any one being true is enough:

  1. Commit author is docsio[bot].
  2. Commit message starts with [docsio].
  3. The commit SHA matches the one Docsio just produced.

Rebuild speed

Push → live: about 60 seconds typically. Variables:

  • Site size — bigger sites take longer to build.
  • Asset count — many images = longer build.
  • AI search reindex — Pro sites with full-text search bar reindex on every publish.

What you don't see

  • No GitHub Actions running. Docsio is the build pipeline. You don't see CI runs in your repo.
  • No staging URL per branch. v1 ships single-branch sync. Each project syncs to one branch at a time. Branch preview deployments are coming in a future release.
  • No PR-mode AI agent. v1 has the AI agent edit project_files directly, then those files get committed on Publish. PR-mode (where the agent opens PRs) is on the roadmap.

When commits happen

Three triggers create a commit on your branch:

  1. You click Publish in the editor. Diff against last commit, atomic commit with [docsio] prefix.
  2. The first sync, in Docsio → GitHub direction. A bigger commit containing your full Docsio site as the initial seed.
  3. Direct git push from anywhere. That's not really "Docsio commits" — that's you using git normally. We pull it back.

Every commit Docsio makes is signed docsio[bot]. Easy to identify in commit history.

Conflict policy

Docsio doesn't lock the editor when sync is on (unlike GitBook). The trade-off: in rare cases where editor and git diverge on the same file, we apply last-write-wins and snapshot the loser to version history.

For most teams this is fine — git pushes and editor edits rarely target the same page within minutes of each other. If your team works that closely on the same content, consider a workflow rule: "use the editor or git for any given week."

Next