GitBook Git Sync with GitHub: a docs-as-code guide

Desired outcome

You want GitHub pull requests to review documentation structure and prose, with GitHub as the source of truth for content and GitBook rendering navigation search and publishing the reader-facing site. The practical decision is to treat GitHub as the reviewable source of truth and GitBook as the presentation layer.

Prerequisites

• A GitBook space with permission to configure integrations and sync. UI labels and behavior are version- and plan-sensitive.
• A GitHub repository and a dedicated docs branch such as main or docs. Agree who may merge to that branch.
• Agreement on content root file naming and front-matter conventions. A common root is docs/ at the repository root.
• Do not store secrets in synced Markdown. Restrict the GitHub app or token to the repository and the minimum permissions needed for the docs workflow.

Procedure

1. In GitBook open the space settings and go to the integration sync area for Git. Authorize the GitHub app for your organization and select the repository <your-org>/<your-repo>.
2. Select the branch for published content. Use a stable branch e.g. main. A separate preview branch can be used for draft work.
3. Set the content directory. If your Markdown lives under docs/ set that as the root so GitBook maps files to pages. Leaving it empty expects Markdown at the repository root.
4. Choose sync direction. Bidirectional allows edits in GitBook to commit back to GitHub and PR edits to appear in GitBook. Define which system wins during review to avoid conflicts.
5. Save and run an initial import. GitBook reads the branch builds a page tree from Markdown files and front matter and creates the space structure.

Local verification you can run in a terminal where you have git access:

git clone https://github.com//.git && git checkout  && ls docs/

Expected check: the files listed match the pages you expect to import. Required permission is read access to the repository. Risk: an incorrect content directory imports unrelated files or misses pages.

Expected checks

• Pages appear in GitBook after sync and match the repository file tree.
• An edit made in GitHub on the configured branch appears in GitBook after the next sync cycle. Make a small test edit merge it then verify the rendered page updates.
• An edit made in GitBook creates a commit or pull request on the configured branch. Repeat the test in the opposite direction and confirm the commit references the same page.
• Navigation internal links images and code blocks render correctly on the published site not just in the editor.

Recovery options

• Pause sync first if edits are colliding. In the space integration settings you can temporarily disable automatic commits from GitBook.
• If a bad commit was pushed from GitBook revert it in GitHub using a normal Git revert on the configured branch then re-run sync.
• If pages duplicated or slugs changed fix front matter or filenames in Git commit and re-sync. Disconnect and reconnect only after confirming credentials repository branch and content directory are correct.
• When bidirectional edits conflict on the same page decide the review winner in advance e.g. GitHub PRs win for published content and GitBook drafts are used for quick fixes only. Note: UI labels and sync behavior are plan- and version-sensitive; legacy CLI workflows do not apply to the current cloud product.