# 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.

<Availability rollout permission="Applications: Read to see an application's sync. Applications: Update, and Knowledge base: Create and Delete, to turn it on, change it, run it or turn it off, signed in to Productmind yourself." />

## Key concepts

**Synced documents.** The documents the sync makes, one per Markdown file (`.md`, `.markdown` or
`.mdx`). They sit in the [knowledge base](/user-guide/knowledge-base#synced-documents) 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](#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

| To | You need |
| --- | --- |
| See an application's **Knowledge Base sync** | **Applications: Read** |
| Turn on, change, run or turn off an application's **Knowledge Base sync** | **Applications: Update**, and **Knowledge base: Create** and **Delete** |

See [Roles and permissions](/user-guide/reference/roles-and-permissions).

## Limits

| What | Limit |
| --- | --- |
| Folders and files in a sync | 20 |
| A synced Markdown file | 300,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.

## Related topics

- [Applications](/user-guide/engineering/applications)
- [Knowledge base](/user-guide/knowledge-base#synced-documents)
- [Documentation links in Marketing](/user-guide/product/marketing-documentation-links)
