Every pylon job needs to know what code the agent is working with. The workspace block in pylon.yaml defines this: where the code comes from, which branch to use, and how it gets mounted into the agent’s Docker container.
Pylon supports four workspace modes: git-clone, git-worktree, local, and none.
git-clone
A fresh clone of a remote repository, created once per job. This gives the strongest isolation — each job starts from a clean state with no leftover changes from previous runs.
workspace:
type: git-clone
repo: git@github.com:acme/nexus.git
ref: main
Fields
| Field | Required | Description |
|---|
type | Yes | Must be git-clone. |
repo | Yes | Repository URL. Use SSH (git@github.com:org/repo.git) for private repos. |
ref | No | Branch, tag, or commit to check out. Defaults to the repo’s default branch. |
Injecting branch from webhook payload
For pylons triggered by pull request webhooks, you can inject the branch name from the payload:
workspace:
type: git-clone
repo: "{{ .body.repository.clone_url }}"
ref: "{{ .body.pull_request.head.ref }}"
SSH URLs require that your Pylon host has an SSH key configured with access to the repository. For GitHub, add the host’s public key as a deploy key on the repository.
git-worktree
Uses a local clone of the repository already on the Pylon host, creating a git worktree for each job. This avoids a full network clone on every run, which is significantly faster on large repositories.
workspace:
type: git-worktree
repo: /home/user/repos/nexus
ref: main
Fields
| Field | Required | Description |
|---|
type | Yes | Must be git-worktree. |
repo | Yes | Absolute path to the local git repository on the host. |
ref | No | Branch, tag, or commit to check out in the worktree. |
Use git-worktree for faster cold starts on large repos. The local clone must already exist and be kept up to date — Pylon does not run git fetch automatically before creating the worktree.
local
Mounts an existing directory from the host into the agent container. No git operations are performed. Use this when you want the agent to work on a local directory that is not a git repository, or when you want it to see uncommitted changes.
workspace:
type: local
path: /home/user/projects/my-service
Fields
| Field | Required | Description |
|---|
type | Yes | Must be local. |
path | Yes | Absolute path to the directory on the host to mount into the container. |
The local workspace mounts the directory directly. The agent can read and modify files in place. Use with caution on directories containing sensitive data or uncommitted work.
none
No codebase is provided to the agent. Use this for pylons where the agent’s task doesn’t require access to code — for example, drafting a report from a webhook payload or querying an external API.
No additional fields are needed.
Comparison
| Mode | Isolation | Speed | Use case |
|---|
git-clone | High | Slower (network clone) | CI-style tasks, PR review, Sentry triage |
git-worktree | Medium | Fast (no clone) | High-frequency jobs on a large local repo |
local | Low | Fastest | Local dev, non-git directories |
none | N/A | N/A | Tasks that don’t need code |