fix(cli): use --base-branch for cloud `ws create`, refuse --branch

Merged
SA
11d ago
+29-8

Bug

Reproduced 2026-10-29 from inside a cloud workspace:

  • superset ws create --environment <id> --branch fv-crossbox-check --name x created a cloud workspace with baseBranch: "fv-crossbox-check" (a branch that does not exist in the repo) and a generated working branch, superset/x-<id>. The help text calls --branch the "Git branch", so users expect it to name the workspace's branch.
  • --base-branch main was refused with "--base-branch does not apply to a cloud workspace", but it is the flag that matches what the API does.

Cause: createCloudWorkspace.ts sent options.branch as branch to cloudWorkspace.create, and startCloudWorkspace (packages/trpc/src/router/cloud-workspace/start.ts) uses that value as baseBranch. The working branch is always generated by workspaceBranchName.

Fix (CLI only)

  • For cloud workspaces, --base-branch is now sent as the API's branch, so it picks the branch the workspace is cut from.
  • For cloud workspaces, --branch is now refused: --branch does not apply to a cloud workspace with the hint Pass --base-branch <name> to pick the branch it starts from.
  • Help text for --branch and --base-branch now describes both host and cloud workspaces.

Why I didn't let --branch name the cloud working branch: that would need a new optional API input, handling for name collisions and branches that already exist, and an API deploy before any CLI could use it. That is more than a small change. The API is untouched, so released CLI builds keep working: they still send branch, and it keeps its current meaning. Behaviour change: scripts that passed --branch to a cloud create now fail with the hint above, where before they silently got a base branch.

Verification

  • New test in createCloudWorkspace.test.ts: --base-branch main sends { branch: "main" } to cloudWorkspace.create. It fails on the old code and passes with this change. I moved the fake API into a helper so the machine-size test can use it too.
  • Checked the --branch refusal and its hint with a throwaway test. It is not committed, because the task asked for one focused test.
  • packages/cli: bun run typecheck passes, biome check . is clean, and bun test gives 446 pass, 0 fail.
  • I didn't create a real cloud workspace with the new build.
  • No i18n impact: the CLI does not use Lingui.

Summary by cubic

Fixes superset ws create for cloud workspaces so --base-branch picks the base branch, and --branch no longer silently selects it.

For a cloud workspace, --branch was previously sent to the API as branch, which the API treats as the base branch; the workspace's own branch is always generated. Now --base-branch is sent as that value, and --branch fails with a hint to use --base-branch instead. Scripts that passed --branch now error where before they got a base branch.

  • Cloud workspaces send --base-branch as the API's branch.
  • --branch is refused for cloud workspaces with a hint to pass --base-branch.
  • Help text for both flags now describes host and cloud behavior.

Summary by CodeRabbit

  • New Features
    • Cloud workspace creation now accepts --base-branch to choose the branch from which its new branch starts.
  • Documentation
    • Clarified that --branch applies to host workspaces and when it is required.
    • Clarified that cloud workspaces always get a new branch, and that --base-branch defaults to the repository’s default branch. For host workspaces, --base-branch is used when the requested branch does not exist and defaults to the project’s default branch.