syncFolder

Sync a folder from GitHub now

Sync a folder that Sasha copies from GitHub now, as Check now does on its card, and return the commit, the time of the last good sync and any error. Admin only. It waits until the sync ends.

Arguments

Argument	Type	Required	Description
`project`	string	required	The project's id: its folder name, for example northwind-advisory
`folder`	string	required	The synced folder's name inside that project, for example handbook

Scopes

synced-folders:sync

Annotations

Read only: no
Destructive: no

When to use

An admin can connect a folder of a GitHub repository to a project in the Sasha web interface (Settings → Shared Drives). Sasha copies the documents into a folder of that project and syncs it every day. Call syncFolder when someone changed the documents in GitHub and wants them in Sasha now, or to see why the last sync failed. It does what Check now does on the folder's card, and it waits until the sync ends.

project (required) is the project's id: its folder name, as in listProjects. folder (required) is the synced folder's name in that project. listProjects shows a syncedFolders list on each project that has synced folders.

The result has folder, source (owner/repo@branch, or owner/repo@branch:path), commit (the GitHub commit now in Sasha), lastSynced (the time of the last good sync in UTC) and error. error is null after a good sync. After a failed sync it is { code, message }, and the last good copy stays in place, so commit and lastSynced describe that copy. Tell the person what the message says; an admin fixes a token problem on the folder's card.

The tool needs the synced-folders:sync scope. Only an admin can hold it, and it is not part of a default grant: an admin's chat in the Sasha web interface has it, and another client has it only when it asks for it by name. No tool adds a synced folder or sets its GitHub token, because a token typed in chat would stay in the conversation.

Example

{ "project": "northwind-advisory", "folder": "handbook" }

The structured result (structuredContent) after a good sync:

{
  "folder": "handbook",
  "source": "northwind/policies@main:docs/handbook",
  "commit": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "lastSynced": "2026-10-21T03:12:00.000Z",
  "error": null
}

After a failed sync, error holds the stored code and message, for example { "code": "GITHUB_TOKEN_INVALID", "message": "GitHub refused the token. Replace it with a token that can read this repository. (...)" }. The codes include GITHUB_TOKEN_INVALID, GITHUB_REPO_NOT_FOUND, GITHUB_BRANCH_NOT_FOUND, GITHUB_PATH_NOT_FOUND, GITHUB_UNREACHABLE and SYNC_FAILED.

Refusals and what to do

A refusal is an error result. Its text is Error in syncFolder: <reason>.

Not found: no active project has this id, or the project has no synced folder with this name. Check the names in listProjects, or ask the person.
If the connection does not hold synced-folders:sync, the tool is not in your tool list, and a call to it returns MCP error -32602: Tool syncFolder not found. Staff and members can never hold the scope. An admin's connection that did not ask for the scope by name does not have it either: use the chat in the Sasha web interface, or reconnect asking for synced-folders:sync. Read the permissions section of getDocs.
Arguments that do not match the schema are refused before the tool runs, for example a missing folder or an extra argument.
internal:unexpected (request <id>): something failed inside Sasha. Quote the request id in suggestImprovement.

listProjects lists the projects, with the syncedFolders of each.
readDoc reads a document of a synced folder, like any other document.
getDocs has a synced-folders section with the same rules.