Skip to main content

Connect a Git Repo

Alpha Feature

Features described on this page are in alpha and subject to change. Some capabilities might require additional access.

note

Enterprise Portal requires a GitHub organization. The content repo integration uses the Replicated GitHub App for syncing and webhooks. GitLab, Bitbucket, and other git providers are not supported.

Enterprise Portal content is driven by a GitHub repo you control. Connecting a repo is a prerequisite to offer versioned docs, advanced theming, and Terraform module delivery.

The Content tab appears when your team has the New Enterprise Portal. The same setting enables the GitHub App workflow for content repositories. Use this workflow to create, authorize, and link repos.

The Vendor Portal walks you through setup in three steps:

Step 1: Create from template​

Go to Enterprise Portal in Vendor Portal. The Content tab is the default landing page. Click Create Repo from Template to generate a new content repository from Replicated's template. This opens GitHub's "Create a new repository" flow, pre-configured with the replicatedhq/enterprise-portal-content template. The repository name is pre-filled as <your-app-slug>-enterprise-portal-content and visibility defaults to private. Choose an owner, adjust the name if needed, and click Create repository on GitHub.

The template includes a working toc.yaml, example pages for installation (Linux and Helm), operations, updates, and support, along with built-in MDX components for interactive install instructions. See Content Template Structure for what's included out of the box.

If you already have a content repository (or prefer to create one from scratch), click Continue to skip this step.

Step 2: Connect GitHub​

Click Connect GitHub and authorize the Replicated GitHub App on your GitHub organization. The App requests read-only access to sync content from your repo into Replicated. It does not write to or modify your repositories. Creating the repo first (Step 1) ensures it's available to grant access to during this step.

To change the linked GitHub account later (for example, if you move your content repo to a different organization), go to Team > GitHub Integration and connect the new account.

note

When installing the Replicated GitHub App, grant access to all repositories you plan to use with Enterprise Portal (content repos AND Terraform module repos). If you need to add access to additional repos later, update the GitHub App's repository permissions in your GitHub org settings (Settings > Integrations > Applications > Replicated > Configure > Repository access).

Select your GitHub organization and the repository containing your Enterprise Portal content, then click Link Repository. When only one GitHub organization or repository is available, it is auto-selected for you.

note

The selected repository must contain a toc.yaml file at the root of its default branch. If none is found, you'll see a warning and won't be able to link the repo. Use the content template (Step 2) or add a toc.yaml manually before linking.

All branches are synced automatically. Pushes trigger automatic syncs via webhook.

Once linked, the Content tab shows sync status for each branch. A branch labeled Fallback means it doesn't match any release version_label on the customer's channel. Fallback content is shown when no version-matched branch is available for a customer. See Naming Your Branches for how to set up version gating.

You can also trigger a manual sync from the Content tab.

Via API:

# Your APP_ID is visible in the Vendor Portal URL when viewing your app,
# or via:
replicated api get /v3/apps | jq '.apps[] | {id, name}'

# List your content repos to get the REPO_ID:
replicated api get /v3/app/<APP_ID>/enterprise-portal/content-repos

# Trigger a sync:
replicated api post /v3/app/<APP_ID>/enterprise-portal/content-repos/<REPO_ID>/sync
important

Content branches must be named with semver versions (e.g., 1.0.0) that match your release version_label values. The main branch is synced but never shown to customers directly. See Naming Your Branches for details.

Adopting template updates​

You create your content repo from the replicatedhq/enterprise-portal-content template. Because you clone the template rather than fork it, your repo diverges as soon as you start customizing content, branding, and navigation.

When Replicated publishes improvements to the template (new MDX components, updated default pages, navigation changes), the Vendor Portal shows a banner on the Content tab with the number of updates available since your last review.

Reviewing updates​

Click Review on the Content tab banner to open the template updates modal. Each update includes:

  • Title and date: What changed and when
  • Impact level: required, recommended, or optional, indicating how important the update is for your portal
  • Summary: A brief description of the change and its effect on your customers' portal experience
  • Affected areas: Tags showing which parts of the template the update touches (for example, installation instructions, navigation, troubleshooting content)
  • Guide link: Opens the full adoption guide on GitHub with step-by-step instructions for applying the change to your repo

Applying an update​

Template updates do not apply automatically. Each update's guide describes what files to copy or modify and what to verify after making the change. Because your repo has diverged from the template, each guide provides targeted adoption steps rather than a wholesale merge.

After reviewing the available updates, click Mark reviewed to acknowledge them. The banner clears until Replicated publishes the next template update. Marking updates as reviewed is per-user, so other team members continue to see the banner until they review it themselves.

On this page