Creating a workspace
The New workspace wizard asks four questions: what it is, which repositories, how its branches reach production, and where each branch runs.
- Reading time
- 3 min read
How it works
A workspace is a branch across a set of repositories, plus a container to work in. Creating one asks four questions, and everything after the first is optional, a name and a list of repos still gets you exactly what it always did.
| Step | What it decides |
|---|---|
| Workspace | The name, the description, an optional deadline, whether the workspace may change code at all, and which coding agent works in it (Claude Code, Codex or OpenCode). |
| Repositories | Which repos are cloned in. Pick an App and its repos come with it; narrowing to one is worth doing when the work only touches one, because the agent reads what is in the workspace. |
| Branching | The branch every repo's working branch is cut from, and this workspace's own promotion chain, ending at production. |
| Environments | Where each of those branches runs, one row per branch, each naming its deploy target. |
Info only is chosen here and fixed afterwards. It is for work that reads code and never
changes it: an audit, a performance review, an investigation. The repos are still cloned so the
agent can read them, and every path by which code could leave is closed, no working branch is
created, the in-box git shim refuses push outright, the push relay refuses it again before any
objects move, and merge requests cannot be opened or landed. The deliverable is a document, not a
diff.
Creating the workspace returns immediately and provisioning happens in the background: a volume, a
one-shot clone of every repo onto the shared branch, then the workspace's box (its container). The status goes
pending → provisioning → running.
Steps
Open Workspaces and press New workspace.
Name the workspace and describe what you are building.
The description is saved as
REQUIREMENTS.mdinside the workspace and kept in sync with it, so the agent reads the same brief you wrote.Set a tentative deadline if there is one.
Used to flag workspaces that are due soon or overdue on the board.
Choose Standard or Info only (read-only).
This one cannot be changed later.
Choose the Agent: Claude Code or Codex.
It starts on your organization's default, and it cannot be changed later either.
Press Next and pick the App, then the repositories this workspace needs.
On Branching, set the branch to cut from and the promotion chain to production.
It starts from your organization's git flow, so most workspaces can leave it alone.
On Environments, name where each branch runs and where DevBench should deploy it.
Only shown if you can manage deployments, otherwise the workspace is created with the defaults.
Create the workspace, and wait for it to finish provisioning.
The card shows
provisioningand thenrunning; the Inbox tells you when it is ready to open.
Worth knowing
Info only cannot be undone. It is a promise the product makes about that workspace, so it is fixed at creation.
Neither can the agent. A workspace's conversations belong to the agent that had them, so switching would abandon them. The next article explains the choice.
Step 4 is hidden entirely if you cannot manage deployments, a step you may not answer is not a step. The workspace is still created.
The creator is assigned to the workspace automatically, so a member never loses the workspace they just made.
Commands
The same job from a workspace's box, for people who live in the terminal.
$ devbench create -n "Name" -r <repo-id>Create a workspace from your own machine with the DevBench CLI.