Skip to content
Componecat Docs

Documentation sync

Documentation that lives next to the code is the documentation that stays true. Documentation sync lets an entity’s documentation sections be sourced from Git: you point a section at a file — or a glob of files — in a repository, and Componecat keeps the section’s content current.

Synced sections behave like any other documentation section: they render Markdown with diagrams, they’re full-text searchable, and AI agents can read them over the MCP server. The difference is that the repository is the source of truth.

Documentation sync is a capability on a GitHub, GitLab, or Bitbucket integration; see Integrations for connecting one.

Enable the capability

Section titled “Enable the capability”

Open the integration and find the Documentation Syncing card. Its only setting is the schedule:

Setting Meaning
Schedule (cron) How often the sync runs. Default 0 */6 * * * — every six hours.

A run sweeps every Git-sourced section in your organization whose repository belongs to that provider — so a GitHub connection refreshes sections sourced from GitHub repositories, and never tries to read a GitLab URL. If your documentation spans several providers, enable the capability on each one.

The credential needs read access to repository contents for the repositories your sections point at. Sections in repositories the credential can’t see fail with a recorded error.

Point a section at a repository

Section titled “Point a section at a repository”

On an entity’s Documentation tab, choose Git Source and fill in:

Field Meaning
Repository URL Optional. Defaults to the entity’s own linked repository.
File Path Pattern The file to pull, or a glob. Required.
Branch Optional. Defaults to the repository’s default branch.

The path can be a single file (docs/architecture.md) or a glob: * matches within a path segment (docs/*.md), and ** matches across segments (docs/**/*.md). When a glob matches several files, their contents are concatenated in one section, each preceded by a comment marking which file it came from.

Leading YAML frontmatter is stripped from each file as it’s pulled in, so documentation written for a static-site generator lands cleanly.

Declare sections in a descriptor

Section titled “Declare sections in a descriptor”

Sections can also be declared in a repository’s componecat.yaml, so the whole setup is version-controlled alongside the entity:

spec:
  docs:
    sections:
      - title: Architecture
        type: architecture
        sourcePath: docs/architecture.md
      - title: Runbooks
        type: runbook
        sourcePath: docs/runbooks/**/*.md

sourceRepository and sourceBranch are available too, and default to the entity’s repository and its default branch. See the descriptor file reference.

Refreshing on demand

Section titled “Refreshing on demand”

Each Git-sourced section shows its sync state — when it last synced, whether a sync is pending, or that the last attempt failed and when it last succeeded.

Refresh on the entity’s Documentation tab syncs that entity’s Git-sourced sections immediately, without waiting for the schedule. It’s available once the entity has at least one Git-sourced section and a Git integration exists to pull from. Run now on the integration’s Documentation Syncing card does the same for every section that provider covers.

Reading sync history

Section titled “Reading sync history”

While the capability is enabled, its card lists recent runs with the number of sections synced and failed, and one error entry per failed section naming the repository, the path, and the reason — a missing file, a branch that doesn’t exist, a permission problem.

Troubleshooting

Section titled “Troubleshooting”
  • A section never syncs. Check that an integration for that repository’s provider exists and has Documentation Syncing enabled. Componecat matches sections to providers by the repository URL.
  • The section is empty. The path pattern probably matched nothing. Confirm the path relative to the repository root and the branch.
  • Content disappeared after an edit in the app. A Git-sourced section is overwritten by its source on the next sync. Edit the file in the repository, or remove the Git source to make the section locally authored again.
  • Everything fails at once. Test the integration’s connection — an expired credential surfaces here first.
Section titled “Related”