Manage Content Versions

Beta Feature

The Enterprise Portal is Beta. Features described on this page are subject to change.

Use versioned docs if you need to maintain different documentation for different versions of your software, for example, distinct install steps or caveats for specific releases.

Each Git branch in your content repo holds one version of your content, with its own table of contents, markdown pages, and theme/branding overrides. Customers don't choose branches. They choose a release from their channel, and Enterprise Portal shows the content from the branch that release resolves to. See Version resolution.

Process

• Initial sync: When you connect a repo, all branches are discovered and synced.
• Push sync: When you push to any branch, a GitHub webhook triggers a sync for that branch only. Pushing a new branch for the first time syncs it automatically. It does not add an entry to the version dropdown. Releases that resolve to the new branch show its content.
• main is never listed: The main branch does not appear in the version dropdown. Customers see its content only when a release does not resolve to any other branch, so do not use main for drafts. Use a branch name that is not a version instead, such as wip/2.1.0. See Naming your branches.
• main as fallback: The main branch serves as the last-resort fallback. If no branch matches the selected version and no lower semver branch exists, main content is shown. This ensures customers always see content. If your repo has no main branch, the branch whose name sorts highest alphabetically is the fallback instead, so keep a main branch in your repo.

Version dropdown

Customers viewing Enterprise Portal see a version dropdown in the header when there are two or more versions available on their channel.

The dropdown lists release version labels, not branch names. Each entry shows the content that its release resolves to, so several entries can show the same content. For example, releases 2.1.1 and 2.1.2 both show the 2.1.0 branch if neither has its own branch.

Releases are sorted newest first by semantic version. Labels that are not valid semantic versions are listed after them.

When a customer visits the portal:

1. If they've previously selected a version (stored in a browser cookie) and it is still available, that version is used
2. Otherwise, the first version in the list (the newest release) is the default

Version resolution

When a customer selects a version from the dropdown, Enterprise Portal resolves which content to show using this order:

1. Pin override: If the vendor has pinned this release to a specific branch, Enterprise Portal uses that branch's content. Pins count as exact matches for version-picker filtering.
2. Exact or normalized match: If a branch has the same name as the selected version, Enterprise Portal uses that branch's content. For example, branch 2.0.0 matches version 2.0.0. Enterprise Portal also handles a v prefix mismatch.
3. Nearest lower branch: If no exact match exists, the system finds the highest semver branch below the selected version. For example, if the customer selects version 2.0.3 and branches 2.0.0 and 1.1.0 exist, the 2.0.0 branch is used.
4. Fallback to main: If no branch is at or below the selected version, the main branch content is served.

This means you only need to create content branches when your documentation actually changes. Patch releases that don't change docs are handled automatically.

Require matching content for release versions

By default, every installable release on the customer's channel appears in the Enterprise Portal version dropdown. If a release does not have a matching content branch, Enterprise Portal uses the normal version resolution flow. It first uses the nearest lower semver branch, then main as fallback.

Keep this behavior off when your documentation does not change for every release. If patch releases 2.0.1 and 2.0.2 use the same instructions as 2.0.0, you do not need separate content branches for each patch release.

Enable Require matching content for release versions when customers should only see releases with explicit version-specific content. When enabled, the version dropdown includes only releases with a matching content branch, a normalized v prefix match, or a pinned version.

If you share one branch across many releases, such as one branch per minor version, most of your releases have no exactly matching branch, and enabling this setting hides them from the dropdown.

Use this setting when fallback content could be misleading, such as when every visible release must have release-specific install steps, upgrade notes, or compatibility guidance.

Pinning releases to branches

By default, the version resolution logic described above handles most cases automatically. You only need to create a content branch when docs change between releases, and patch releases resolve to the nearest lower branch.

For cases where the automatic resolution picks the wrong content, you can pin a specific release to any existing branch. For example, if release 1.2.0 is a mandatory migration step with special instructions that don't exist in the 1.1.0 docs, you can pin 1.2.0 to the 2.0.0 branch (which contains the migration guide).

To pin a release, use the Pin release controls at the bottom of the Content Repository card on the Content tab. Select the release version label and the target branch, then click Pin. The pin takes effect immediately.

Pins follow their branch. When you push changes to the branch that a release is pinned to, the pinned release shows the updated content. If you delete that branch, Enterprise Portal moves the pin to the nearest lower semver branch. If there is no lower semver branch, the pin is kept and a notice is shown for it on the Content tab.

To remove a pin, click the delete icon next to the version in the Content Repository card and confirm.

Naming your branches

Branch names decide which content each release shows. They do not control which versions customers see in the dropdown or the order of the dropdown. See Version dropdown.

• Give a release its own content: Name the branch the same as the release version_label (e.g., branch 2.1.0 for release 2.1.0). A v prefix mismatch is handled automatically (branch v2.1.0 matches label 2.1.0 and vice versa).
• Share content across releases: Create one branch for the first release that needs the content. Later releases without their own branch use the nearest lower branch. For example, branch 2.1.0 covers 2.1.1, 2.1.2, and later releases until a higher branch exists.
• Pre-release labels sort below their release: A label such as 2.2.0-beta.1 or 2.2.0-g1a2b3c comes before 2.2.0 in semantic version order, so a branch named 2.2.0 does not cover it. It resolves to the nearest lower branch, such as 2.1.0. To cover every 2.2.0 pre-release and every later 2.2.x release with one branch, name the branch 2.2.0-0, which is the lowest possible 2.2.0 pre-release.
• Do not give working branches version names: A branch such as 2.1.3-wip is a valid pre-release version, so it becomes the nearest lower branch for 2.1.3 and every later release until a higher branch exists. Use a name that is not a version, such as wip/2.1.3.

A branch whose name is not a version (e.g., wip/2.1.3 or release-1) is used only for a release whose label matches the branch name exactly, or as the fallback when your repo has no main branch.

Adding versions

1. Create a new branch matching your release version label: git checkout -b 2.0.0
2. Update the docs content for the new version
3. Push the branch. Enterprise Portal syncs it automatically, and releases that resolve to the branch show the new content

Enterprise Portal does not create branches for you. Create a branch for each release where your documentation changes, or see Automating branch creation.

Automating branch creation

Replicated publishes a reusable GitHub Actions workflow, as an example you can adopt or adapt, that creates a content branch for every release on the channels you choose. It cuts each branch from your base branch and only creates branches, never updating or deleting them.

Whether it helps depends on how often your content changes:

• Your content changes meaningfully with most releases. The workflow fits. You were going to create those branches anyway, and it removes a step that is easy to forget.
• Your content stays the same across most releases. You do not need it. Each branch is a copy of your base branch from the moment the job ran, so you would hold many identical branches and maintain one per release if the content later diverges.

In the second case, leave Require matching content for release versions off so a release resolves to the nearest lower branch, and pin any release where resolution picks the wrong content.

Version gating by channel

The version dropdown lists only releases promoted to the customer's assigned channel, however you name your branches. For example, a customer on the Stable channel with releases 1.0.0 and 2.0.0 sees those two versions, whether you have a branch for each release or one 1.0.0 branch that both releases resolve to. A customer cannot open a version that is not on their channel, including by entering its URL.

The local CLI preview also respects this filtering. When you switch customers in the preview toolbar, the version dropdown shows the versions that customer would see based on their channel's releases.

Version URL

Versioned pages use the pattern /{version}/path/to/page:

• /2.0.0/installation/helm
• /1.0.0/getting-started

When a customer switches versions via the dropdown, the portal swaps the version segment in the URL and navigates to the same page path in the new version.

Removing versions

To remove a version's dedicated content branch, delete the branch from your git repo. The branch disappears from the Content tab after the next sync.

If a release with that version label still exists on a customer's channel, it still appears in the version dropdown by default. The portal resolves it using the version resolution chain: nearest lower semver branch, then main as fallback. To hide releases without matching content branches, enable Require matching content for release versions in the Content Repository card.

Overrides

In toc.yaml, the docs template supports an overrides map.

Currently the only supported override is home, which replaces the default version landing page with a custom markdown page:

overrides:
  home: pages/getting-started.md