⚠️ WARNING: In a Git repository, the 'workspaces' section i

Error message

⚠️  WARNING: In a Git repository, the 'workspaces' section is recommended in wmill.yaml.\n   Consider adding a workspaces section to map workspace names to Windmill instances.\n   Run 'wmill init' to recreate the configuration file with proper workspace setup.

What it means

The Windmill CLI (`wmill`) prints this warning from `validateBranchConfiguration` when `wmill push`, `pull`, or `push gitsync-settings` runs inside a git repository but the `wmill.yaml` config file has no `workspaces` section (or it defines zero workspaces). The workspaces section maps local workspace names to git branches and Windmill instances, which lets the CLI auto-detect which workspace to sync based on the current branch. It is a non-fatal advisory: the command continues, but branch-based auto-detection will not work.

Source

Thrown at cli/src/core/conf.ts:424

  const rawBranch = getCurrentGitBranch();

  const originalBranchIfForked = getOriginalBranchForWorkspaceForks(rawBranch);

  let currentBranch: string | null;
  if (originalBranchIfForked) {
    // The fork targeting itself is announced by tryResolveBranchWorkspace;
    // this validation detail stays at debug to avoid a near-duplicate line.
    log.debug(
      `Workspace fork detected from branch name \`${rawBranch}\`. Validating workspace configuration using original branch \`${originalBranchIfForked}\``
    );
    currentBranch = originalBranchIfForked;
  } else {
    currentBranch = rawBranch;
  }

  // In a git repository, workspaces section is recommended
  if (!workspaces || getWorkspaceNames(workspaces).length === 0) {
    log.warn(
      "⚠️  WARNING: In a Git repository, the 'workspaces' section is recommended in wmill.yaml.\n" +
        "   Consider adding a workspaces section to map workspace names to Windmill instances.\n" +
        "   Run 'wmill init' to recreate the configuration file with proper workspace setup."
    );
    return;
  }

  // Warn if multiple workspaces map to the same git branch
  const branchToWsNames = new Map<string, string[]>();
  for (const name of getWorkspaceNames(workspaces)) {
    const entry = workspaces[name] as WorkspaceEntryConfig;
    const branch = getEffectiveGitBranch(name, entry);
    const existing = branchToWsNames.get(branch);
    if (existing) {
      existing.push(name);
    } else {
      branchToWsNames.set(branch, [name]);
    }

View on GitHub (pinned to e474e8803c)

Solutions

Run `wmill init` to regenerate `wmill.yaml` with a proper workspaces section (back up custom settings first).
Manually add a `workspaces:` section to `wmill.yaml` mapping workspace names to their git branches, e.g. `workspaces: { my-ws: { gitBranch: main } }`.
Use `wmill gitsync-settings pull` against an existing workspace to pull its git-sync configuration into the file.
If branch auto-detection is intentionally not needed, pass `--skip-branch-validation` or an explicit `--workspace` to silence the flow.

Example fix

# before (wmill.yaml)
include_scripts: true
include_flows: true

# after
include_scripts: true
include_flows: true
workspaces:
  main:
    gitBranch: main
  staging:
    workspace_id: staging-ws
    gitBranch: develop

Defensive patterns

Strategy: validation

Validate before calling

// before running wmill push/pull in CI or scripts
const cfg = await Deno.readTextFile("wmill.yaml");
if (!/^workspaces:\s*$/m.test(cfg) || /^workspaces:\s*\{?\s*\}?\s*$/m.test(cfg.trim())) {
  console.warn("wmill.yaml has no workspaces section — run 'wmill init' or add one");
}

Prevention

Always bootstrap projects with `wmill init` so the workspaces section is generated.
Commit a `wmill.yaml` containing a workspaces mapping to the repo so every clone has it.
Lint `wmill.yaml` in CI for a non-empty `workspaces` key.
Don't strip the workspaces section when hand-editing the config.

When it happens

Trigger: Running `wmill push`, `wmill pull`, or `wmill gitsync-settings push/pull` (without `--skip-branch-validation` or an explicit workspace override) while: (1) cwd is a git repository, (2) `wmill.yaml` exists but lacks a `workspaces:` key, or (3) the `workspaces` key exists but is empty or has no entries.

Common situations: Developers created `wmill.yaml` by hand with only top-level sync settings, initialized the repo before the workspaces feature existed, copied a minimal config from another project, or ran `wmill init` in a directory then stripped the workspaces section. Also common after cloning a repo whose `wmill.yaml` was gitignored.

Related errors

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/a86a9aeb6f491b86. Report an issue: GitHub.