Connecting a repo
A script that files work needs its repo connected first. These routes list, probe, connect and disconnect repos. Like the other board routes they can change in any release, and kraft repo connect --json is the stable way to do the same. The routes that change a connected repo's settings are in the schema.
| Route | What it does |
|---|---|
GET /api/repos | Lists the connected repos and workspaces. |
POST /api/repos/probe | Reads a repository and proposes how to connect it. |
POST /api/repos | Connects a repository. |
DELETE /api/repos?path= | Disconnects a repository. |
GET /api/repos
Answers the connected repos and workspaces, and the checkout the server was started in when it isn't connected yet.
curl -s http://127.0.0.1:8765/api/repos | jq '.repos[].path'
| Field | Type | Meaning |
|---|---|---|
repos | list | One entry per connected repo, as repos.yaml holds it, defaults included. |
workspaces | object | The workspaces: section, by workspace ID. |
suggested | string or null | The git checkout the server was started in, when it isn't connected yet. |
POST /api/repos/probe
Reads a repository and changes nothing. The answer is the proposal that connecting would save.
| Field | Type | Default | Meaning |
|---|---|---|---|
path | string | required | The absolute path of the repository. |
detect | boolean | true | With false the route answers only what needs no detector table: the resolved path, name, branch, submodules, beads and forge. |
test_command | string | none | The root's test command, in place of the proposed one. "" declares that the repo has no tests. |
forge | string | none | github or gitlab: the forge you already know for a host that names none, so the answer doesn't ask. Added in 2.5 |
How connect proposes commands says how a proposal is made and what limits the probe. The probe runs in a process of its own with a two-minute limit.
| Status | When |
|---|---|
400 | The path isn't a git repository, detectors.yaml doesn't load, or the probe ran past two minutes. |
422 | path is relative. |
429 | Two probes are already running. Try again shortly. |
POST /api/repos
Connects a repository: it probes it, saves the entry to repos.yaml, and indexes the repo for search. It answers 201 with the saved entry and the probe's proposal.
curl -s -X POST http://127.0.0.1:8765/api/repos \
-H 'Content-Type: application/json' \
-d '{"path": "/home/me/src/app", "test_command": "pytest -q"}'
| Field | Type | Default | Meaning |
|---|---|---|---|
path | string | required | The absolute path of the repository. |
name | string | the directory name | The repo's name. |
default_chain | string | default | The chain its items run when none is named. |
test_command | string | the probe's proposal | The root's test command. "" declares a repo with no tests. |
setup_command | string | the probe's proposal | The command that prepares a worktree. "" declares none. |
enabled | boolean | true with a test command or test scopes, else false | Whether auto-intake and an agent may file work on the repo. A person can file on a disabled repo by hand. |
forge_account | string | none | The forge account the repo uses. Added in 2.5 |
The body also takes test_scopes, forge, project, models, deny_tools and steering, the fields of the same names in repos.yaml.
Commands an agent gives are held for a person. When the request comes from a worker session or the MCP server and gives a test_command, a non-empty setup_command or test_scopes, the repo is saved disabled, whatever enabled says, and the answer carries held.
| Status | When |
|---|---|
400 | The path isn't a git repository, or the probe fails and the body doesn't give both commands. |
403 | forge_account from a worker session or the MCP server: a repo's account is a person's choice. Added in 2.5 |
409 | The repo is already connected. |
422 | The path is relative, the repository has no commit yet, enabled: true has no test command or scopes, forge_account names no account, or repos.yaml wouldn't load with the entry. detail says which. |
DELETE /api/repos?path=
Disconnects the repo at path: it removes the entry from repos.yaml and from the search index. No file of the repository is touched and no work item is dropped. kraft repo disconnect calls it. It answers 204 with no body.
| Status | When |
|---|---|
404 | path isn't a connected repo, or is relative. |
409 | The repo has open items, paused ones included. The answer gives the count: complete, cancel or abandon them first. |
409 | The repo's add-on library is still named by configuration, or an add-on is busy. The answer names where. |
422 | A workspace in repos.yaml still names the repo. |