Engineering

Knowledge Base sync

The Knowledge Base sync keeps an application's documentation in the knowledge base the same as in its repository. You pick a branch and the folders or files to sync, and every Markdown file under them becomes a read-only document that each push to the branch updates. Your team and your agents read the docs where they work, and the docs stay where your engineers edit them.

Key concepts

Synced documents. The documents the sync makes, one per Markdown file (.md, .markdown or .mdx). They sit in the knowledge base under one document named after the application, nested the way the folders are, and are read-only there: the repository is where they're edited. Nothing is ever written to the repository.

Folders and files. What the sync brings in. A folder brings every Markdown file under it, sub-folders included; a file brings that one Markdown file. A new sync starts with docs.

The person it reads as. Background syncs read the repository with the Git connection of whoever last saved the settings.

Published at. Where a folder's or file's docs are published for your customers, such as your documentation site. Marketing then links customer release notes, blog posts and emails to those pages. Under a folder, each file's page is the address plus its path in the folder, without the extension: with docs published at https://docs.example.com, docs/guide/setup.md opens at https://docs.example.com/guide/setup.

Status. Not synced yet before the first run, Syncing while a run is under way, Up to date once it has finished, and Stopped when the last run couldn't finish. The tab says why it stopped, and what to do. Paused means your plan no longer includes the sync: see If your plan no longer includes the sync.

Syncing an application's docs

The sync is on the application's Knowledge Base sync tab. An application has the tab when your organization has the sync, through its plan or turned on for it by Productmind, and the application has a repository.

To sync documentation from the repository

  1. Open the application and choose Knowledge Base sync.
  2. Choose the Branch to sync from. It starts on the application's base branch.
  3. Under Folders and files, keep docs, or choose Add a folder or file and pick one from the repository. Add up to 20, and order them with the arrows.
  4. Leave Available to agents on for agents to search the documents and ground their work in them, or turn it off.
  5. Turn on Sync docs into the Knowledge Base.

The first sync runs at once, and the documents appear in the knowledge base under one document named after the application.

To change what is synced

  1. Change the Branch, the Folders and files or Available to agents.
  2. Choose Save changes.

When you remove a path, choose whether to Keep the documents, as ordinary documents you can edit, or Delete the documents. After a save, the sync compares every document with the branch again.

To say where the docs are published

  1. Under Folders and files, enter the address in the folder's or file's Published at field, starting with https://. Below the field, an example shows the page one file opens at.
  2. Choose Save changes.

Leave the field empty for docs that are not published: nothing customer-facing links to them.

To sync now

Choose Sync now. The sync compares every document with the branch again, and the tab shows the result when it finishes.

To stop syncing

  1. Turn off Sync docs into the Knowledge Base.
  2. Choose whether to Keep the documents, as ordinary documents you can edit, or Delete the documents, then choose Turn off.

The settings stay for the next time you turn the sync on.

How the sync behaves

Each push to the branch is applied within seconds:

  • a changed file updates its document;
  • a renamed or moved file keeps its document, with its ID, links and comments;
  • a deleted file removes its document.

Once an hour Productmind also checks the branch, so a push it missed is synced anyway.

The tab shows where the sync stands: when it last synced and from which commit, what the last run added, updated, renamed and deleted, the files it skipped and why, and whose Git connection reads the repository in the background.

For GitHub repositories, pushes arrive through the Productmind GitHub App. For GitLab and Bitbucket, Productmind adds a webhook to the repository when you save, which needs the connection to be allowed to manage webhooks. Until it is, the sync runs on the hourly check.

If your plan no longer includes the sync

When your organization moves to a plan without the Knowledge Base sync, an application's sync that is still on is paused, not removed:

  • it stops following the repository: neither pushes nor the hourly check update its documents;
  • its documents stay in the knowledge base, read-only;
  • the Knowledge Base sync tab shows Paused, and its one action is Turn off sync.

To turn off a paused sync

  1. Open the application and choose Knowledge Base sync.
  2. Choose Turn off sync.
  3. Choose whether to Keep the documents, as ordinary documents you can edit, or Delete the documents, then choose Turn off.

If your plan includes the sync again before you turn it off, the sync resumes by itself and catches up with the branch within the hour.

Permissions

ToYou need
See an application's Knowledge Base syncApplications: Read
Turn on, change, run or turn off an application's Knowledge Base syncApplications: Update, and Knowledge base: Create and Delete

See Roles and permissions.

Limits

WhatLimit
Folders and files in a sync20
A synced Markdown file300,000 characters

Synced documents count toward your workspace's document limit.

Troubleshooting

The Knowledge Base sync stopped

The tab says why, with what to do:

  • The branch doesn't exist: choose another branch and save.
  • The person it reads the repository as no longer has access: choose Save to sync as you, and the sync reads it with your Git connection from then on.
  • The repository couldn't be reached: check the application's Git connection, then choose Sync now.

Synced documents stopped updating and can't be edited

Your plan may no longer include the Knowledge Base sync. Open the application's Knowledge Base sync tab: if it shows Paused, choose Turn off sync and keep the documents to edit them as ordinary documents, or change to a plan that includes the sync to resume it.

A file wasn't synced

A file the sync skipped is listed on the tab with its reason: not a Markdown file, larger than 300,000 characters, not UTF-8 text, or over your workspace's document limit.

Last modified on