Sync

Synchronizing folders & git repositories to a Windmill instance is made easy using the wmill CLI. Syncing operations are behind the wmill sync subcommand.

Having a Windmill instance synchronized to folders & git repositories allows for local development through the VS Code extension.

VS Code extension

Build scripts and flows in the comfort of your VS Code editor, while leveraging Windmill UIs for test & flows edition.

Raw Syncing

Raw syncing will soon become the default.

Raw syncing is a one-off operation with no state maintained. When using Windmill EE and Git sync, this is what you should use since Git sync will always keep your git repo up-to-date. When not used in with Git sync. It's best used for making backups, cloning a complete workspace, and similar one-off operations.

Raw syncing is done using wmill sync pull & wmill sync push

Pulling

wmill sync pull will simply pull all files from the currently selected workspace and store them in the current folder. Overwrites will not prompt the user. Make sure you are in the correct folder or you may loose data.

Pushing

wmill sync push will simply push all local files to the currently selected workspace, creating or updating the remote equivalents.

Pull API

The wmill sync pull command is used to pull remote changes and apply them locally. It synchronizes the local workspace with the remote workspace by downloading any remote changes and updating the corresponding local files.

wmill sync pull [options]

Options

Option	Parameter	Description
-h, --help	None	Show help options.
--fail-conflicts	None	Error on conflicts (both remote and local have changes on the same item).
--yes	None	Pull without needing confirmation. The command proceeds automatically without user intervention.
--plain-secrets	None	Pull secrets as plain text. Secrets are downloaded without encryption or obfuscation.
--json	None	Use JSON instead of YAML. The downloaded files are in JSON format instead of YAML.
--workspace	<workspace>	Specify the target workspace. This overrides the default workspace.
--debug, --verbose	None	Show debug/verbose logs.
--show-diffs	None	Show diff information when syncing (may show sensitive information).
--token	<token>	Specify an API token. This will override any stored token.
--base-url	<baseUrl>	Specify the base URL of the API. If used, --token and --workspace are required and no local remote/workspace will be used.
--raw	None	Push without using state, just overwrite. (Default, has no effect.)
--stateful	None	Pull using state tracking (create .wmill folder and needed for --fail-conflicts).
--skip-variables	None	Skip syncing variables (including secrets).
--skip-secrets	None	Skip syncing only secret variables.
--skip-resources	None	Skip syncing resources.
--include-schedules	None	Include syncing schedules.
--include-users	None	Include syncing users.
--include-groups	None	Include syncing groups.
--include-settings	None	Include syncing workspace settings.
--include-key	None	Include workspace encryption key.
-i, --includes	<patterns>	Comma-separated patterns to specify which files to take into account (among files compatible with Windmill). Overrides wmill.yaml includes. Patterns can include * (any string until '/') and ** (any string).
-e, --excludes	<patterns>	Comma-separated patterns to specify which files to NOT take into account. Overrides wmill.yaml excludes.
--extra-includes	<patterns>	Comma-separated patterns to specify which files to take into account (among files compatible with Windmill). Useful to still take wmill.yaml into account and act as a second pattern to satisfy.

Push API

The wmill sync push command is used to push local changes and apply them remotely. It synchronizes the remote workspace with the local workspace by uploading any local changes and updating the corresponding remote files.

wmill sync push [options]

Options

Option	Parameter	Description
-h, --help	None	Show help options.
--workspace	<workspace>	Specify the target workspace. This overrides the default workspace.
--debug, --verbose	None	Show debug/verbose logs.
--show-diffs	None	Show diff information when syncing (may show sensitive information).
--token	<token>	Specify an API token. This will override any stored token.
--base-url	<baseUrl>	Specify the base URL of the API. If used, --token and --workspace are required and no local remote/workspace will be used.
--fail-conflicts	None	Error on conflicts (both remote and local have changes on the same item).
--raw	None	Push without using state, just overwrite. (Default, has no effect.)
--stateful	None	Push using state tracking (use .wmill folder, required for --fail-conflicts).
--skip-pull	None	(Stateful only) Push without pulling first.
--yes	None	Push without needing confirmation.
--plain-secrets	None	Push secrets as plain text.
--json	None	Use JSON instead of YAML.
--skip-variables	None	Skip syncing variables (including secrets).
--skip-secrets	None	Skip syncing only secret variables.
--skip-resources	None	Skip syncing resources.
--include-schedules	None	Include syncing schedules.
--include-users	None	Include syncing users.
--include-groups	None	Include syncing groups.
--include-settings	None	Include syncing workspace settings.
--include-key	None	Include workspace encryption key.
-i, --includes	<patterns>	Comma-separated patterns to specify which files to take into account (among files compatible with Windmill). Patterns can include * (any string until '/') and ** (any string).
-e, --excludes	<patterns>	Comma-separated patterns to specify which files to NOT take into account.
--extra-includes	<patterns>	Comma-separated patterns to specify which files to take into account (among files compatible with Windmill). Useful to still take wmill.yaml into account and act as a second pattern to satisfy.
--message	<message>	Include a message that will be added to all scripts/flows/apps updated during this push.

wmill.yaml

Note that you can set the default TypeScript language and explicitly exclude (or include) specific files or folders to be taken into account with a wmill.yaml file.

includes: ['f/**'] # uses "*" or uncomment this line to include everything. Note that wmill will only consider files with valid path (u/ or f/, with the right extension)
excludes: [] # excludes patterns here

defaultTs: 'deno' # bun is the default, set it to deno if you primarily use deno to avoid needing the .deno.ts extension

All sync options for your workspace can be found on this file:

export interface SyncOptions {
  raw?: boolean;
  yes?: boolean;
  skipPull?: boolean;
  failConflicts?: boolean;
  plainSecrets?: boolean;
  json?: boolean;
  skipVariables?: boolean;
  skipResources?: boolean;
  skipSecrets?: boolean;
  includeSchedules?: boolean;
  includeUsers?: boolean;
  includeGroups?: boolean;
  includeSettings?: boolean;
  message?: string;
  includes?: string[];
  extraIncludes?: string[];
  excludes?: string[];
  defaultTs?: "bun" | "deno";
  codebases?: Codebase[];
}

Example repo for syncing with Windmill in git

We provide an example repo for syncing with Windmill:

windmill-sync-example

Demo repository showcasing how to sync Windmill with a remote.

Cloning an instance

Instances can be cloned with Windmill CLI. This is useful for instance migration or for setting up a new (prod) instance with the same configuration as an existing one.

Pulling an instance

To pull instance users, groups, settings and configs (=worker groups+SMTP) from the instance use wmill instance pull.

You can skip any of those using --skip-XXX.

You can also pull all workspaces at the same time by adding the --include-workspaces option. It will setup for each a local workspace (including a folder in the current directory) with a prefix specific to the instance (based on the name you've given to the instance).

Pushing an instance

To push to an instance use wmill instance push. It takes the same options as pulling an instance.

When using --include-workspaces, you will also have to select the instance prefix of the local workspaces you want to push (make sure you're in its parent folder).

During the push process, you will be prompted to decide whether to re-encrypt the secrets of the workspace on the remote instance. In the case of instance migration, it is recommended to select "no" as the secrets are already encrypted with the correct key.