Workspaces

A workspace is the access and configuration boundary for a team and its Git repositories, sessions, tickets, bots, and operational settings.

Creating a workspace

Workspace creation establishes the first repository and creator membership.

1. Open Workspaces and select New Workspace.
2. Enter a name, repository URL, optional access token, and default branch.
3. Select Create.
4. Open the workspace and verify repository access before starting sessions.

The creator is assigned automatically. Workspace creation and management require the applicable workspace permissions.

Repositories

A workspace contains one or more equal repositories; there is no primary repository.

Field	Purpose
Name	User-facing repository name.
Git Repository	Clone, fetch, and push URL.
Personal Access Token	Optional credential for private Git and pull-request operations; protected at rest.
Default Branch	Starting branch used when no override is selected.
Folder Name	Unique subfolder used inside session working copies.

Every session checks out all workspace repositories. Branch selectors appear per repository wherever a session, ticket, automation, plan, or deployment needs a starting branch.

Chat and Develop working copies

Working-copy behavior depends on session mode.

Chat sessions with the same resolved branch selection share a persistent working copy. Chat sessions with different selections use separate copies. Develop sessions use isolated working copies. Changing a default branch affects new sessions; existing sessions keep their original branch selection.

Workspace configuration

Workspace settings establish defaults and integrations used by new work.

Area	Purpose
Repositories	Git URLs, credentials, folders, and default branches.
Users	Workspace membership.
Environment Variables	Values exposed to workspace sessions.
Hooks and Tasks	Commands run at selected session lifecycle points.
System Prompt	Optional workspace-wide agent instructions.
Tickets Configuration	Ticket lifecycle, sync, templates, and approval defaults.

Review defaults after repository, credential, branch, or team changes. Existing sessions retain configuration captured when they started where applicable.

Custom system prompt

A custom system prompt adds workspace-specific instructions to every applicable session.

Keep it short, stable, and relevant to all repositories in the workspace. Put task-specific requirements in the session, workflow, bot, or ticket instead. Do not place credentials or other secrets in prompts.

Environment variables

Workspace variables supply configuration to sessions and workspace tasks.

• Names must be unique within the workspace.
• Mark sensitive values as secret so they are protected at rest and masked in the UI.
• Existing processes do not receive edited values; start a new session or rerun the task.
• Treat values printed by scripts or agents as disclosed, even when the UI masks them.

After rotation, update the variable, terminate sessions that may retain the old value, and verify the new credential with a controlled run.

Session hooks and tasks

Hooks run configured workspace tasks when selected session lifecycle events occur.

Use hooks for dependency setup, validation, tests, and cleanup. Configure tasks first, then attach them to the required event. Set working directory, timeout, failure behavior, and any condition supported by the editor. Test each task directly before enabling it as a hook.

A failed blocking hook can prevent lifecycle progression. Open the session's hook result, correct the command, credentials, working directory, or timeout, and retry the user action. See Session Hooks.

Workspace users

Workspace membership grants visibility but permissions determine available actions.

Add or remove users from the Users area. Removing a member blocks future workspace access; review their active sessions, assigned tickets, automations, and approval responsibilities before removal. Role changes take effect according to the updated permission set.

Ticket configuration

Ticket configuration controls external source settings, the workspace-wide lifecycle, approvals, queue behavior, and start templates.

Enable Merge First in the Tickets tab to apply Merge First to every ticket in the workspace. Leave it disabled to use QA First. Individual ticket starts and Start Ticket Templates cannot override this setting. Changing it applies the selected lifecycle to subsequent transitions and lifecycle-dependent status reporting for all workspace tickets.

Configure GitHub or Azure DevOps/TFS sync only with a dedicated least-privilege token. Test import, status update, and pull-request behavior with a non-critical item before enabling automatic start rules. See Ticket Sync and Tickets.

Start Ticket Templates

A Start Ticket Template stores repeatable ticket-start settings.

Templates can set the model, workflow, branch selections, assignments, priority, session options, and allowed agent capabilities. They do not define ticket lifecycle, which is configured once for the workspace. Review templates after renaming workflows, changing repositories, or rotating integrations. An empty explicit capability selection grants none; use the unrestricted control when all enabled capabilities are intended.

Permissions

Permissions separate workspace access from administration.

Typical controls cover viewing, creating, editing, deleting, member management, and ticket configuration. Grant workspace deletion and member management only to administrators. The workspace capability ceiling can further limit what members may exercise inside that workspace.

Troubleshooting

These checks cover common workspace incidents.

Symptom	Check
Repository clone or fetch fails	Verify URL, token validity and scope, network access, and default branch spelling.
Repository cannot be deleted	Complete or cancel active sessions; confirm it is not the workspace's last repository.
Wrong branch is used	Check that repository's default and the per-repository selection on the session or ticket.
Variable is missing	Confirm its name, workspace, and whether the session started after the value was added.
Hook fails	Review task output, working directory, environment, timeout, and host permissions.
User cannot see the workspace	Confirm membership, enabled account status, and required role permissions.
Ticket sync fails	Verify the selected source, dedicated credentials, project or repository settings, filters, and status mapping.