GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing gitbook.com — Enabling GitHub Sync | GitBook Documentation

For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

GitHub Sync configuration options.

Open Git Sync for your site

From your site, open Git Sync in the sidebar.

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 in to that user account and unlink your GitHub account (done in settings) before logging back in and linking your current account.

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.

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. GitBook replaces the section with the content of the selected branch. If the repository is empty, or is behind GitBook because recent change requests haven’t been exported yet, that content is lost from the section and your published site.

You choose a direction every time you set up Git Sync, including when you reconnect it or re-create an existing connection. Before you start the sync, confirm the repository, branch, and direction. If you choose GitHub → GitBook, check that the branch’s latest commit includes your most recent merged change requests.

If content was replaced, see Troubleshooting to restore it.

Set the project directory

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

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.

Review advanced options

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

Sync your site

Click Sync to start the initial sync.

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.

Last updated 2 months ago

Was this helpful?

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.