Workflow Strategies

Workbench supports three workflow strategies that control how work leaves a workspace and lands on your main branch. The default is Pull Request. You can set a different global default in Settings > Git and override it per repository in Settings > Repository.

Pull Request

The standard workflow. Each workspace creates a branch, pushes it to the remote, and opens a pull request through the SCM integration. Archive-on-merge is available when enabled.

Workspaces created under this workflow fetch the remote before branching, so the worktree starts from the latest remote-tracking HEAD. SCM polling checks PR status in the background so the project view stays current.

Trunk

A local-first workflow designed for teams (or solo developers) who squash-merge directly to main without pull requests. Workspaces merge locally and archive immediately — no remote PR is involved.

Creating workspaces

Trunk workspaces branch from the local main ref without fetching the remote. This makes workspace creation instant and network-independent.

Shipping a workspace

When a trunk workspace has commits ahead of main, the Ship button appears in the right sidebar panel. The panel shows how many commits are ahead. Clicking Ship runs the following sequence:

Sync — merges local main into the workspace branch so the squash merge is clean.
Squash merge — squash-merges the workspace branch onto main with a single commit.
Archive — archives the workspace and removes the worktree.

Each step emits real-time progress in the sidebar panel (syncing, merging, archiving, done). If the sync step encounters merge conflicts, the ship is blocked and a system message listing the conflicting files is sent to the workspace’s chat session so the agent (or you) can resolve them. After resolving, click Ship again.

A per-workspace lock prevents concurrent ship and sync operations on the same workspace.

Syncing with main

Right-click a trunk workspace in the sidebar and choose Sync with Main to merge local main into the workspace branch on demand. This is the same sync step that Ship runs first, but without the squash merge and archive. A toast reports the result: already current, synced, or blocked (with the reason).

Push and pull

The sidebar shows push (arrow up) and pull (arrow down) buttons on a trunk repository’s header row when the local main branch is ahead of or behind the remote.

Push sends local main commits to the remote.
Pull fetches the remote and fast-forwards local main. If the branches have diverged, a modal opens with resolution options (see Divergent pull below).

A background poller checks the sync state every 60 seconds. The sidebar badge updates immediately after a ship, push, or pull completes rather than waiting for the next poll cycle.

Divergent pull

When both local main and the remote have new commits, clicking Pull opens a modal with four options:

Option	Behavior
Merge (recommended)	Creates a merge commit combining both sets of changes.
Rebase	Replays local commits on top of the remote changes.
Fast-forward only	Refuses to proceed on diverged branches — use this to confirm no local commits exist.
Open terminal	Opens a terminal for manual resolution.

If Merge or Rebase encounters conflicts, Workbench attempts automatic resolution using the workspace’s agent. If the agent cannot resolve all conflicts, you can retry, open a terminal, or abort the pull entirely. Aborting returns the repository to its pre-pull state. Pull attempts persist across app restarts, so closing Workbench mid-merge resumes where it left off on the next Pull click.

See Git Worktrees > Divergent Branch Pull for the full resolution flow.

Sync status badge

The repository header in the sidebar shows a sync state badge when the local main and remote have drifted:

Ahead — local has commits not on the remote.
Behind — remote has commits not on local.
Diverged — both ahead and behind.

A tooltip shows the count (e.g. “3 commits behind origin”). The badge clears when local and remote are in sync.

Conflict routing

When a ship or sync operation is blocked by merge conflicts, Workbench inserts a system message into the workspace’s chat session listing the conflicting files. This message is visible in the chat panel and directs the agent to resolve the conflicts.

Repo terminal

Each repository row in the sidebar has a terminal icon. Clicking it opens (or focuses) a dedicated terminal session rooted in the repository’s main checkout — outside any workspace worktree. Use this for ad-hoc git operations on main (interactive rebase, tag management, manual merges). The terminal workspace is hidden from the normal workspace list and is automatically removed when its last terminal tab is closed.

SCM polling

Trunk workspaces are excluded from SCM polling entirely. Because they don’t use pull requests, polling would only produce “no pull requests found” noise.

Candidate Promotion

Candidate Promotion is defined but not yet supported at runtime. Selecting it in settings preserves the configuration, but workspaces fall back to Pull Request behavior until support ships. The settings dropdown disables the option for new selection while keeping it visible for repositories that already have it configured.

The planned model: workspaces squash-merge locally (like Trunk), but the branch is retained until the change is promoted through a validation pipeline. Archive triggers on promotion rather than on merge.

Configuration

Global default

Settings > Git > Workflow Strategy sets the default for all repositories. Options: Pull Request (default) and Trunk. Candidate Promotion appears only if already selected.

Per-repo override

Settings > Repository > Workflow Strategy overrides the global default for a single repository. Options: Inherit (uses the global default), Pull Request, and Trunk.

When a per-repo override is set, a badge appears next to the repository name in the sidebar: PR, Trunk, or CP. For Candidate Promotion, the badge includes a tooltip explaining that the configured workflow differs from the effective one.

The Tauri command get_repo_workflow returns both the configured and effective workflow for a repository, so the UI can surface the distinction when they differ (e.g. Candidate Promotion configured but Pull Request effective).