Knowledge Base Sync

Your knowledge base lives in your repository, and that copy is the source of truth. Knowledge base sync keeps a copy of it on the CodeLantern platform, so the portal's Knowledge analytics can show how your knowledge is growing across repositories.

Sync is one-way, from your repository to CodeLantern. It never writes to your repository, and editing the knowledge base always means changing the files in your repository and merging the change.

Sync is on by default. On GitHub it runs once you merge the workflow cl-init adds, and you can turn it off by deleting that workflow. On Azure Repos it's set up when the repository is added in the portal and stays on while the repository is configured.

Sync doesn't change what your skills read. Skills read the knowledge-base files in your working copy, so a session has the knowledge it needs whether or not sync is set up.

What's synced

• Synced: every markdown file under .codelantern/knowledge-base/, including adr/, as it is on your default branch. Each file can be up to 1 MB. On GitHub, the knowledge base can have up to 50 files and 5 MB in total. On Azure Repos, it can have up to 500 files.
• Not synced: .codelantern/work-items/, the plans, session logs, and decisions for each issue. They stay in your repository.

Each sync reflects the whole knowledge base on the default branch, so an entry you delete from the repository is also removed from CodeLantern's copy.

GitHub repositories

On GitHub, a workflow in your repository sends the knowledge base to CodeLantern.

Set it up

1. Run /cl-dev:cl-init. It adds .github/workflows/cl-kb-sync.yml for your default branch. It doesn't run the workflow.
2. Commit the workflow and the knowledge-base files and merge them into your default branch.

The workflow needs the CodeLantern GitHub App installed on the repository and the repository registered in the portal. It needs no tokens or secrets.

When it runs

• Automatically, on every push to the default branch that changes a file under .codelantern/knowledge-base/. Merging a pull request that updates the knowledge base, such as one from /cl-dev:consolidate, counts.
• By hand, from the repository's Actions tab: choose CodeLantern KB Sync, then Run workflow on the default branch. Do this after you first add the workflow if the knowledge base didn't change in the same push.

Check that it worked

Open the latest CodeLantern KB Sync run in the Actions tab:

• A successful run means CodeLantern accepted the knowledge base. It updates its copy in the background, so the Knowledge analytics in the portal can take a short while to reflect it.
• "No knowledge-base files found; nothing to sync." The repository has no knowledge-base files on that branch. The run makes no changes, and CodeLantern's existing copy stays as it was.
• "CodeLantern token exchange failed." The CodeLantern GitHub App isn't installed on this repository, or its installation isn't connected to your CodeLantern organization. Check both on the portal's Integrations page, then run the workflow again.
• "KB sync failed (HTTP 409)." The repository isn't registered in the portal. Add it under Repositories, then run the workflow again.
• "KB sync failed (HTTP 400)." CodeLantern couldn't accept the knowledge base as sent, for example because it has more than 50 files, a file over 1 MB, or more than 5 MB in total.
• Any other "KB sync failed" error. The workflow already retries short-lived errors. Run it again, and if it keeps failing, contact CodeLantern support with a link to the run.

Azure Repos repositories

On Azure Repos, sync is automatic and needs no workflow or pipeline in your Azure DevOps organization. When an admin adds an Azure Repos repository in the portal, CodeLantern registers a Service Hook (Azure DevOps's webhook subscription) on that Azure DevOps project. After that, every push to the repository's default branch tells CodeLantern to read the knowledge base at the tip of that branch. Azure DevOps doesn't run GitHub Actions workflows, so a .github/workflows/cl-kb-sync.yml file in an Azure Repos repository has no effect.

What the admin needs

When adding the repository, the admin needs:

• An active personal connection to Azure DevOps.
• Permission to manage Service Hooks on the project, which Azure DevOps grants to Project Administrators.

If either is missing, the repository is still added, and the portal shows a warning that Knowledge Base sync couldn't be enabled, with the reason. Fix the cause, then remove the repository and add it again, which sets up sync. Removing a repository clears its settings in the portal, so if you'd rather keep them, contact CodeLantern support instead. Sync is also set up again when a repository that needs reconfiguration is reconfigured in the portal.

To read the repository, sync uses the Azure DevOps connection of a member of your organization: the person who pushed, or another member with an active connection. Keep at least one member's Azure DevOps connection active, or sync stops.

Check that it worked

Azure sync doesn't produce a run log in your organization. After a push to the default branch, check the Knowledge analytics in the portal: the entry totals should include that repository's knowledge base. If it doesn't after a few minutes, check that the push was to the default branch, that the repository shows as Active in the portal, and that at least one member has an active Azure DevOps connection, then contact CodeLantern support.