Relationship between GitBook and GitHub

Owned by Rachel Lawson (Unlicensed)
Aug 08, 2023
2 min read

We use GitBook as a collaborative editing and publishing tool for our key products, like the Specifications and Use-cases, but the key storage mechanism of those documents is in our GitHub repositories, using the Markdown standard.

This approach means that we have a long-term home for all of the versioned content but can swap in an out collaborative editing and publishing tools as the environment demands.

GitBook synchronises with GitHub

We configure each space in GitBook to synchronise its content with a branch in a repository in GitHub.

So, for example, the bb-workflow collection in GitBook contains (at least, it will grow!) three spaces; development, 1.0 and 1.0.1.

The development space always connects to the main branch in GitHub, synchronising changes both ways – changes made in GitBook are added to GitHub using a commit and commits in GitHub are sent back to GitBook as changes.

Version control in GitHub

As all version control is managed in GitHub, we can ensure that versions are retained for the long term, as required by those planning to build systems over the long term against a developing standard.

Making a release in GitHub

To make a numbered release of a building block:

  1. Ensure that the Development space is approved for making a release

  2. Create a new branch, named “1.1” or whatever number is agreed, based upon the main branch

  3. In GitBook, create a new space, give it the same name as the branch and synchronise it with GitHub, choosing the repository in question and the branch just created

  4. Choose to copy initial content FROM GitHub TO GitBook

  5. Reduce the users who can edit content in the branch to the QA Approvers group only

  6. Publish the space in the collection. Edit the path to say, using workflow as example, “example-1.1” so that is remains unique

  7. Make the space the default space in the collection

  8. Optionally update the main specification space to point to the newly released version (which will likely mean a new release of that space, of course)

Comparing released versions

Because the definitive storage location of the content is in GitHub, we are able to make us of its incredibly powerful comparison tools to find differences between versions of content.

We can make comparisons in many different ways and the GitHub documentation is always the best resource for understanding these however, here are a few examples:

Comparison of the latest changes made to the main specification since the 1.0.1 release