One Repo, Two Editors: Making GitBook's Git Sync Work for Engineers and Writers

Someone on the API team spots the wrong default value in the rate-limit docs. They fix it in the repo where the docs "obviously" live, open a pull request, merge — and the published site doesn't change. The docs actually live in GitBook. Meanwhile a technical writer fixes the same page in GitBook's editor. Now there are two versions of the truth, and nobody knows which one shipped.

GitBook's Git Sync exists to collapse that split. It binds a GitBook space to a repository branch and synchronizes content in both directions: the repo holds plain Markdown, the visual editor works on top of it, and commits flow either way. With a couple of conventions, it gives engineers pull requests and CI while writers keep the editor they like. Without conventions, it produces commit spam and sync conflicts. Here's what it syncs, an arrangement that avoids the common traps, and where it bites.

What Git Sync actually syncs

A space is bound to one branch of one GitHub or GitLab repository. Content lives there as Markdown files, and the page tree — the sidebar and published navigation — is described by a structure file alongside them (SUMMARY.md in GitBook's layout). The sync runs both ways:

• A save in GitBook's editor becomes a commit on the bound branch.
• A commit or merged pull request on that branch updates the space, and through it the published site.

Two things to know before designing around this. The binding is per space and per branch, which is what makes multi-environment setups possible. And GitBook's sync behavior, supported providers, and plan availability have changed over time — check the current product documentation before standardizing on it.

Pull requests for docs, an editor for everyone else

Once the repo is the storage layer, documentation inherits Git's defaults: review on every change, branch protection, and CI checks such as Markdown linting or link checking. An engineer proposes a docs change the same way they propose a code change. Writers never touch a terminal, and their saves land in the same history.

The per-branch binding also supports a staging pattern: a docs-staging branch synced to a preview space, main synced to production. Changes graduate by merging branches, not by publishing in a separate tool.

A worked setup: preview space plus PR review

For a site with both engineering and writing contributors, you'll typically need someone with org or repository admin rights to authorize GitBook's GitHub/GitLab integration on the repo once. Then:

1. Create a docs-staging branch from main in GitHub or GitLab.
2. In GitBook, connect the production space to main and a second, preview space to docs-staging, from each space's integration settings.
3. Route engineering changes through pull requests against docs-staging; let writers edit the preview space directly.
4. Merge docs-staging into main when a change is ready. Production follows.

Adding a page from the engineering side touches two files: the Markdown itself and the structure file that places it in the navigation. A new guides/rate-limits.md needs a matching SUMMARY.md entry:

# Table of contents

* [Introduction](README.md)

## Guides

* [Rate limits](guides/rate-limits.md)
* [Authentication](guides/authentication.md)

The check that the wiring works: merge the pull request, open the preview space, and confirm the page appears in the sidebar where the SUMMARY entry put it. If the file exists but the navigation didn't change, the structure file is the suspect — a wrong path there silently orphans content.

Where it bites

The conflict row deserves emphasis, because the feature can't solve it for you. Bidirectional sync means two live editing surfaces over the same files; if a writer and an engineer edit the same page in the same afternoon, something has to give. Teams that are happy with Git Sync usually have an explicit rule — reference pages are repo-only, tutorials are editor-only — rather than trusting conflict resolution to sort it out.

Verify on a scratch repo first

Because exact behavior varies by plan and release, trial it cheaply before rolling it out:

1. Connect a test space to a scratch repository, edit a page in GitBook, and confirm the commit appears on the bound branch.
2. Merge a pull request that adds a page plus a SUMMARY.md entry, and confirm the space shows the page in the right spot.
3. Edit the same page in the editor and via a quick push within a few minutes, and watch how the conflict is surfaced — better to learn that on a throwaway setup than during a launch.

If those three checks behave the way your team needs, the payoff is real: one history, one review process, and an editor non-engineers will actually use. The rule that keeps it together is simple — decide, per content area, which surface is the primary way to edit, and let the sync handle the rest.