Workspace Configuration
Git workflow, agent instructions, and permission settings per workspace
Workspace Configuration
Each workspace can be configured with git workflow settings, custom agent instructions, and permission controls. Configuration is stored as a JSON object (gitConfig) on the workspace.
Git Workflow Settings
Branching Strategy
| Strategy | Description |
|---|---|
none | No branch management — worker uses current branch |
trunk | All work on the default branch |
feature | Feature branches from default branch |
gitflow | Develop/release/hotfix branches |
custom | Custom branching rules |
Additional branch settings:
defaultBranch— the main branch name (main,master,dev, etc.)branchPrefix— prefix for worker branches (e.g.,feature/,buildd/)useBuildBranch— usebuildd/task-{id}naming convention
Commit Style
| Style | Description |
|---|---|
conventional | Conventional commits (feat:, fix:, chore:, etc.) |
freeform | No enforced format |
custom | Custom commit message rules |
Optional commitPrefix adds a prefix to all commit messages (e.g., [JIRA-123]).
PR Behavior
requiresPR— whether workers must create a PR before completingtargetBranch— which branch PRs should target (defaults todefaultBranch)autoCreatePR— automatically create a PR when the worker completes
Agent Instructions
Custom Instructions
The agentInstructions field contains free-form text that is prepended to the agent's system prompt. Use this for workspace-specific rules:
Always run tests before committing.
Use the project's ESLint config — do not disable rules.
Database migrations must be reviewed before merging.CLAUDE.md Support
When useClaudeMd is true (default when a CLAUDE.md file exists in the repo), the agent loads project instructions from CLAUDE.md automatically. This works via the settingSources: ['project'] option in the Claude Agent SDK.
Permission Bypass
The bypassPermissions flag allows agents to skip interactive permission prompts during execution. When enabled:
- File edits are auto-approved
- Bash commands run without confirmation
This is useful for fully autonomous execution in CI or trusted environments.
The workspace value only applies once configStatus is admin_confirmed.
On an unconfigured workspace the flag is ignored and the runner's own local
setting decides — so setting it to false here does not guarantee bypass is
off. Save the config once to make the workspace value authoritative.
Dangerous commands (rm -rf /, sudo) are blocked by a pre-tool hook that
exists on the Claude backend only — Codex has no equivalent hook and is
governed by its sandbox mode instead. If the workspace, mission, role or task
routes work to Codex, do not rely on that blocklist. It is also narrow by
design: it matches rm -rf / and rm -rf ~, not rm -rf . or rm -rf ../...
Configuration Object
The commonly-used fields of WorkspaceGitConfig. This is not the whole type —
it also carries backend selection, budget caps, sandbox and network policy,
auto-merge rules, thinking and effort settings, and more:
interface WorkspaceGitConfig {
// Branching
defaultBranch: string;
branchingStrategy: 'none' | 'trunk' | 'gitflow' | 'feature' | 'custom';
branchPrefix?: string;
useBuildBranch?: boolean;
// Commit conventions
commitStyle: 'conventional' | 'freeform' | 'custom';
commitPrefix?: string;
// PR/Merge behavior
requiresPR: boolean;
targetBranch?: string;
autoCreatePR: boolean;
// Agent instructions
agentInstructions?: string;
useClaudeMd: boolean;
// Permissions
bypassPermissions?: boolean;
}Configuration Status
Workspaces track a configStatus field:
| Status | Meaning |
|---|---|
unconfigured | Default — no git config has been saved |
admin_confirmed | A workspace admin has saved the configuration |
Saving the config sets admin_confirmed, and that write requires workspace
admin or owner — a plain member gets 403. This matters because
admin_confirmed is what makes the workspace's bypassPermissions value take
effect at all.
Writing Config: Two Endpoints, Two Behaviours
POST /api/workspaces/{id}/config is a full-object replace, not a patch. It
rebuilds the git config from the request body and applies its own defaults to
anything absent — so posting a single field resets defaultBranch to main,
branchingStrategy to feature, requiresPR and bypassPermissions to
false, and drops every field it does not know about. That includes backend
selection, budget caps, sandbox policy, auto-merge rules and the rest.
To change one setting without disturbing the others, use
PATCH /api/workspaces/{id} with a gitConfig object, which shallow-merges into
the existing config:
curl -X PATCH https://buildd.dev/api/workspaces/{workspace-id} \
-H "Authorization: Bearer bld_xxx" \
-H "Content-Type: application/json" \
-d '{ "gitConfig": { "requiresPR": true } }'The dashboard form uses the POST route, which is correct there because the form
submits every field it manages.