Enabling GitHub Sync

Sync your GitHub repo with GitBook

This guide will take you through setting up your GitBook site with a repo on GitHub.

GitHub Sync configuration options.

1

Open Git Sync for your site

From your site, open Git Sync in the sidebar.

2

Connect GitHub

Connect the GitHub account that has access to the repository you want to sync.

If you see a 'Potential duplicated accounts' error message at this step, this means your GitHub account is already linked with another GitBook user account.

To help you identify which accounts are linked, you will have to log out from this session and log in using the sign-in with GitHub method.

If you already know your GitBook account associated with GitHub you can log into that user account and unlink your GitHub account (done in settings) before logging back in and linking your current account.

Read more on our troubleshooting page.

3

Select a repository and branch

Under Source repository, select the repository that contains your documentation. Select the branch that GitBook syncs with. If the branch doesn’t exist, GitBook creates it during the initial sync.

Can’t find your repository? If you can't find your repository in the list, make sure that you've installed the GitBook GitHub app in the right scope (i.e. your personal account or the GitHub org where the repository lives). You should also check that you’ve configured the correct repository access in the GitBook GitHub app.

4

Choose an initial sync direction

Choose the source of truth for the initial sync. Select Swap direction if the repository content should replace the GitBook content.

GitHub → GitBook can replace your section’s content. If you select an empty repository, GitBook can replace your section with the repository’s empty content.

Before you start the initial sync, confirm the repository, branch, and direction. Make sure the destination content is safe to replace.

5

Set the project directory

If your documentation lives in a subdirectory, enter it under Project directory. GitBook stores your site’s docs.yaml file in this directory. Use this configuration if your docs live within a monorepo.

6

Map your spaces

Under Content mapping, assign each space to a directory in the repository. Use ./ for paths relative to the project directory. Use / for paths from the repository root. Newly linked spaces sync automatically.

7

Review advanced options

If needed, configure agent instruction files, a commit message template, or fork previews.

8

Sync your site

Click Sync to start the initial sync.

9

Write and commit

Merge a change request in GitBook to commit its changes to GitHub. Commits to GitHub sync back to GitBook.

Exclude a space from site-wide Git Sync

In the site’s Git Sync content mapping, click the remove icon next to the space you want to exclude. You can then configure Git Sync from that space.

If the site already has Git Sync, GitBook asks you to choose a scope:

• Select the site’s repository and branch to add the space to site-wide Git Sync.
• Select an independent repository and branch to configure Space Git Sync.

If the site doesn’t use Git Sync, GitBook configures Git Sync independently for the space.

To configure Git Sync for a single space, in the space you want to sync, click Set up next to Git Sync in the space header. From the provider list, click GitHub Sync.

The GitHub app that powers our GitHub integration is currently not available to customers on GitHub Enterprise Server instances.