Managing Multiple Product Releases with GitBook’s Built‑In Versioning

Problem

Teams that ship multiple product releases often need to keep documentation in sync with each version. When the docs live in the same repository as the code, a reader looking for v1.2.0 should see the exact set of pages that shipped with that release, not the latest main branch.

How GitBook Versions Work

GitBook treats every Git branch as a potential version and can publish releases from tags. When the Versions feature is enabled, GitBook watches the connected repository for the branches and tags you specify. Each matching tag becomes a selectable entry in the version dropdown on the published site. Readers can switch between versions, and each version maintains its own search index and theme settings.

Worked Example

Suppose you have a repository my‑docs hosted on GitHub. The documentation source lives in the docs/ folder.

1. Connect the repository to a GitBook space via the dashboard (Integrations → GitHub).
2. In the space settings, enable Versions.
3. Choose which refs to publish: set Branches to main and Tags to a pattern like v*.
4. Develop on a feature branch:

   git checkout -b feature/new-api
   # edit docs/
   git add docs/
   git commit -m 'Add API reference for v1.0'
   git push origin feature/new-api
   

5. When the feature is ready, merge into main:

   git checkout main
   git merge --no-ff feature/new-api
   git push
   

6. Tag the release:

   git tag v1.0.0
   git push origin v1.0.0
   

7. GitBook detects the new tag, triggers a build, and publishes it as version v1.0.0. The version dropdown now shows main and v1.0.0.

Trade‑offs and Limitations

• Each published version consumes storage and bandwidth. Keeping many old versions can increase costs, especially on the free plan which limits the number of published versions.
• Version availability depends on correct tagging. A missing or malformed tag will not appear in the UI, and readers will not be able to access that release’s docs.
• Custom JavaScript or plugins must be version‑aware; otherwise they may break when a reader switches versions because the underlying assets are loaded from the selected version’s build.

Getting Started and Verification

To confirm that the setup works as expected:

1. After pushing a tag, open the GitBook space’s Activity log. You should see a build entry for that tag.
2. Visit the published site and open the version dropdown. The new tag should be listed alongside main.
3. Select the tag and verify that the content matches the commit you tagged (e.g., a specific heading or file that exists only in that commit).
4. Optionally, run gitbook doctor locally to ensure your local build matches the remote version.

Actionable Closing

Start with a test repository that contains a few branches and tags. Connect it to a GitBook space, enable Versions, and publish a single tag. Observe the build logs and the version dropdown to confirm the mechanism. Once you are comfortable, apply the same process to your product documentation, monitor version usage, and prune old releases if storage becomes a concern.