roark · docs
docs/managed-workspaces.md

Managed workspaces

How Roark prepares clone-backed workspaces and copies ignored host-local files into them.

Last updated

Edit on GitHubView Markdown

#Workspace layout

By default, workspaces live under:

text
~/.roark/workspaces/<owner>-<repo>/issue-<number>
~/.roark/workspaces/<owner>-<repo>/pr-<number>

Issue workflow runs use issue-<number> workspaces. revise-pr uses pr-<number> workspaces.

Each issue gets a persistent workspace and a branch named:

text
roark/issue-<number>

The workspace starts from Git state. Ignored host-local files are not present unless explicitly copied.

#Copy ignored local files

If verification fails because ignored local files are missing, for example:

text
Missing .secrets/env/dev/local.web.env

add the ignored path to .roark/config.json:

json
{
  "workspace": {
    "strategy": "clone",
    "copyToWorktree": [".secrets/env"]
  }
}

copyToWorktree is nested under workspace. The same relative path is used as the source in the control checkout and the destination in the managed workspace.

#Safety rules

Roark rejects entries that are:

  • absolute paths
  • empty strings
  • parent traversal such as ../secret
  • .git paths
  • glob-looking paths containing *, ?, or [

Before copying, Roark requires the destination path itself to be ignored by Git:

bash
git check-ignore .secrets/env

After copying, Roark checks git status --porcelain -- <path> and refuses to continue if copied content is visible to Git.

#Copy behavior

  • Missing sources fail clearly before any configured paths are written.
  • Existing destination paths are removed first.
  • Directories are copied recursively.
  • Symlinks are dereferenced into target contents rather than preserved as symlinks.
  • File modes such as 0600 are preserved.
  • Copied files are refreshed before workspace run and before verification.

Do not store secret values in .roark/config.json; store only path names such as .secrets/env.

#Workspace commands

bash
roark workspace list
roark workspace remove --issue 123
roark workspace remove --pr 98
roark workspace prune --older-than 30d

list and prune include both issue and PR revision workspaces. Dirty workspaces require --force. Use it only after confirming that recoverable work is disposable.

#Next steps