Remote Git Backends

Remote Git backends store a Synth project in a shared Git repository. Use this when a team wants project memory that is durable, reviewable, and portable between machines or deployments.

This is different from a Git watcher:

Feature	Use it for
Remote Git backend	Storing the Synth project itself.
Git watcher	Reading source docs from a repo into a Synth project.

Many teams use both: a remote backend stores the generated Synth project, and a Git watcher keeps selected source docs fresh.

When To Use It

Use a remote Git backend when you want to:

• import an existing Synth project on a new machine
• keep multiple Synth projects in one shared repository
• review project memory changes through Git
• recover a project from Git if local state is lost
• let a deployment pull project memory on startup

Do not use this as a replacement for ingestion. Git storage saves Synth project files. To turn a source repository into knowledge, use Ingest or a Git Watcher.

Repository Layout

Use one folder per Synth project:

synth-knowledge/
  projects/
    backend-api/
      knowledge/
      .synth/
    customer-portal/
      knowledge/
      .synth/

The project folder must be relative, for example:

projects/backend-api
projects/customer-portal
team-memory/platform

Avoid absolute paths and parent-directory segments.

Import From The Web App

Open Projects and choose Import.

Fill in:

Field	What to enter
Name	Local project name, for example backend-api.
Storage	Git - Store the Synth KB or plans in a repo.
Repository URL	The Git repository, for example https://github.com/your-org/synth-knowledge.git.
Branch	Usually main.
Project folder	A relative folder such as projects/backend-api.
Git credential	A stored GitHub PAT credential for private repositories.

The folder must already contain a Synth project when importing.

Credentials are organization-wide, not stored in or assigned to a Project. The picker shows your Personal credentials and every Global credential. Global credentials are selectable by everyone and editable only by administrators. See Credentials for the full visibility model.

Create A Git-Backed Project

Open Projects and choose New when you want Synth to create a project and store it in Git from the beginning.

You can also connect Git storage later from the project card's Storage action. Use this when you started locally and later decide the project should be shared with a team.

Changing storage does not ingest source code. It only changes where Synth stores project files.

What Gets Stored

A healthy project folder usually contains:

knowledge/
  index.md
  concepts/
  entities/
  sources/
.synth/
  metadata.json
  stats.json
  graph.db

Runtime caches and watcher state stay local to the Synth instance and should not be committed to the backend repository.

Verify An Import

After importing, check:

1. Knowledge shows imported pages.
2. Graph shows nodes and connections.
3. Search finds phrases from the imported pages.
4. Explore returns project-specific evidence with exact revisions.
5. MCP tools can see the project with synth_list_projects and synth_status.

If exact pages exist but Explore returns nothing, inspect the active canonical index and Project selection.

API

Use the web app for the first import. For scripted setup, see the REST API reference.

Best Practices

• Use one folder per Synth project.
• Reuse organization credentials across Projects instead of copying tokens.
• Keep project names and folder names stable.
• Use Import for existing Synth projects.
• Use Storage when an existing local project needs Git later.
• Use Git watchers for source repositories that should continuously feed a project.
• Use remote Git backends for storing the Synth project itself.
• Verify pages, graph, Explore search, and exact reads after the first import.

Troubleshooting

Problem	What to check
Import says the folder does not exist	Confirm project_subdir exists on the selected branch.
Import creates an empty project	Use Import existing Synth project or set sync_on_create: true.
Graph is empty	Confirm the remote project has Markdown pages under knowledge/.
Pages exist but Explore is unready	Publish or repair the canonical Project read snapshot.
Push fails	Check Git credentials and branch permissions.