Set up GitBook Git Sync with GitHub or GitLab as the source of truth

Problem and useful takeaway

Your team edits documentation in GitBook, but code review and version history live in Git. Without a connection between the two, a change made in the GitBook editor never reaches the repository, and a commit pushed to Git never appears on the published site. The practical takeaway is to configure one GitBook space to track one branch in one repository. GitBook becomes the rendering and publishing layer, while the repository remains the reviewable source of truth.

Prerequisites

• Admin access to the GitBook workspace or the specific space you want to sync.
• A GitHub or GitLab repository containing Markdown documentation.
• Permission to install or authorize the GitBook Git application for that provider.
• A branch you can push to, such as main or a dedicated docs branch.
• Confirmation that Git Sync is included in your GitBook plan. Exact integration names, plan limits, and availability vary by workspace.

Connect a repository to GitBook Git Sync

1. Open the GitBook space, go to Settings, then Integrations, and select Git Sync.
2. Choose Connect GitHub or Connect GitLab. Authorize the GitBook app when your provider prompts you.
3. Select the repository and the branch to sync.
4. If your Markdown files live in a subfolder, enter the content directory path, for example docs/. Leave this blank if the Markdown is at the repository root.
5. Start the initial import. Avoid editing pages in GitBook until the import finishes and the page tree appears.
6. Open the space and confirm that the navigation reflects the files in the repository.

Example repository mapping

Repository	Branch	Content directory	Result
acme-docs	main	docs/	GitBook renders files under docs/ and writes UI edits back to main
acme-docs	main	(blank)	GitBook renders Markdown at the repository root

Verify the sync is working

1. Check that the GitBook page tree matches the files and folders in the configured branch.
2. Make a small edit in GitBook, such as correcting a typo, and save it. Look for a new commit from GitBook in the configured branch on GitHub or GitLab within the expected sync window.
3. Push a trivial Markdown change from your local clone, wait for the sync interval, and confirm the corresponding GitBook page updates without a manual re-import.
4. Open a deep link on the published site after import. Missing pages usually indicate the content directory or root file is misconfigured.

Local change example

Run these commands in a local terminal where you have read and write access to the repository. Replace placeholders such as OWNER, REPO, and docs/getting-started.md with values for your own project.

git clone https://github.com/OWNER/REPO.git
cd REPO
git checkout -b docs-update
# Edit docs/getting-started.md in a text editor
git add docs/getting-started.md
git commit -m "Update getting started guide"
git push origin docs-update

Expected checks: the commit appears on GitHub or GitLab, and after GitBook’s sync interval the corresponding page updates in GitBook and on the published site. Relevant risks: pushing directly to a protected branch may be rejected, and direct commits bypass review if your team requires pull requests before changes reach GitBook.

Recovery options

Git Sync changes state by writing commits to the branch and importing content into GitBook, so rollback options apply.

• Pause or disable Git Sync in space settings to stop write-back immediately.
• Revert the bad commit in Git, push the revert, and let GitBook re-import. If the page tree is inconsistent, disconnect Git Sync, restore the space from a known-good state if available, then reconnect.
• If an organization policy change revoked app permissions, re-authorize the GitBook app in your Git provider and reconnect the integration.
• Keep a clean branch or tag before enabling sync so you can rebuild the space if sync conflicts corrupt the page tree.

Limitations

• GitBook may commit directly to the selected branch unless your workspace uses a pull-request flow. Do not point two-way sync at a protected branch that requires reviews unless you use a dedicated branch.
• Avoid large binary assets and generated files in the synced directory; they create noisy commits and slow imports.
• Concurrent edits to the same page in GitBook and Git can result in last-writer-wins overwrites. Coordinate through pull requests.
• Plan limits, app scopes, and organization policies can silently block sync. Verify the app’s repository access after any org policy change.
• Exact integration labels, sync intervals, and monorepo path behavior are workspace-specific. Verify them in your GitBook settings rather than assuming fixed values.

Practical way to check the result

Create a scratch page in GitBook, save it, then confirm a new commit and file appear in the configured branch. Push a one-word Markdown change from your local clone, wait for the sync window, and confirm the GitBook page updates without a manual re-import. Check a deep link on the published site after import; missing pages usually mean the content directory or root file is misconfigured.