Local filesystem (file://) source

The local provider lets the orchestrator run workflows from a git repository that already lives on the agent’s filesystem — cloned via a file:// URL rather than fetched from a remote forge. There is no webhook from GitHub or GitLab; the operator drives runs explicitly with the kici-admin CLI or a generated post-receive hook.

This is an operator-curated source, not daily developer CI. Use it for globally-registered or policy workflows the operator controls — a vendored repo baked into an agent image, a repo synced onto a host out-of-band, a golden internal pipeline. For ordinary per-developer CI driven by pull requests and pushes, use the GitHub App provider or the universal-git provider against a real forge.

Trust caveat (read first)

A local source uses signature verification none — there is no remote forge to sign the webhook payload, so the orchestrator cannot authenticate the trigger. Only register repos you trust. Anyone who can reach the orchestrator’s webhook route for this source, or push to the repo on disk, can drive a run. Treat the repo path as a trusted operator input, the same way you treat the orchestrator’s own configuration.

Register a source

kici-admin source add local \
  --org <orgId> \
  --path /abs/path/to/repo \
  --name my-local-repo

• --path must be an absolute directory on the agent filesystem. It is the base path the orchestrator’s lock-file fetcher reads (<path>/.kici/kici.lock.json) and the base for the file:// clone the agent performs. The path must also be a directory on the orchestrator’s own host. An orchestrator that finds no directory there skips the source and logs Skipping local source — repoBasePath not a directory on this peer. In a cluster, only the orchestrators that host the path serve the source.
• --clone-url-base <url> is optional. By default the agent clones via file://<path>. Supply a git:// or http:// base when the agent does not share the orchestrator’s filesystem and must fetch the repo over a git server instead (see “Per-scaler reachability” below).

Update the path or name later:

kici-admin source update-local <id> --path /new/abs/path
kici-admin source update-local <id> --name new-name

Remove it:

kici-admin source remove <id> --local

With --local, the argument is the source id that source add local printed, not a routing key.

List and inspect (local sources render their repoBasePath):

kici-admin source list --org <orgId>
kici-admin source get <id>

Trigger runs

A local repo has no forge to send webhooks, so you trigger runs yourself.

One-shot, by hand:

kici-admin source trigger-local <id>

The command reads the repo’s current HEAD ref and commit SHA, builds a GitHub-shaped push payload, and POSTs it to the orchestrator’s generic webhook route. Override the ref/sha/event explicitly when needed:

kici-admin source trigger-local <id> --event push --ref refs/heads/main --sha <sha>

The payload’s before commit sets the push’s changed files (before..sha). It defaults to the parent of --sha, read from the repo; pass --before <sha> to cover several commits. A root commit, or a repo the command cannot read, sends no before: the push then has no range, and a paths filter matches conservatively.

A local source has no provider API to list changed files. The agent decides paths filters from its clone: the run starts with an __init__ job, and a push that touches none of the paths runs no other job.

On every push, via a hook:

kici-admin source install-hook <id>

This writes a post-receive hook into the repo so that every push to it triggers a run automatically — the local equivalent of a forge webhook. The hook forwards each pushed ref’s old commit as --before, so the run’s changed files are exactly the pushed commits. A push that creates a branch forwards a zero before; the payload names the pushed branch as the default branch, so that push has no range and matches paths filters conservatively.

Per-scaler reachability (operator’s responsibility)

The orchestrator accepts a local source on any scaler backend and does not verify that the repo is actually reachable inside the agent. Making the path reachable is the operator’s job. On a container or Firecracker scaler the orchestrator logs a reachability warning when it registers the source, but it does not reject it.

Scaler	How the repo must be reachable in the agent
bare-metal	The agent runs on the host, so the --path host directory is used directly.
container	Bake the repo into the agent image, or bind-mount it at the same absolute path the source was registered with. Alternatively register --clone-url-base pointing at a git server the container can reach.
Firecracker	The repo must be present on the microVM rootfs at the registered path, or reachable via a --clone-url-base git server.

If the path is not reachable inside the agent, the clone fails at run time — the run is created and then fails, rather than being silently dropped.

See also

• Universal-git provider — for a remote forge (or any http:// git server) when there is no shared filesystem.
• GitHub App provider — the flagship source for pull-request CI with Checks.