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.

Stateful Syncing

Stateful syncing is currently the default but will soon require the --stateful flag

Stateful syncing is best used when your Git repo and Windmill workspace might diverge (because of not using Git Sync) and you want to keep track of the state the last time you pulled to check for merge conflicts. The CLI will automatically maintain state for you and ensure modifications that happen concurrently on the remote and locally stay in sync.

Pulling

Pulling with wmill sync pull --stateful will first update the internal sync state, and then generate a diff between your local files and this state, only updating the actually modified files. Possible conflicts will warn the user.

Pushing

Pushing with wmill sync push --stateful will push all local files to the remote and then update the internal state to avoid being out-of-sync due to the push. Using sync push without --skip-pull will start the push by doing a pull first to ensure the user is not overriding changes made to the remote.

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
--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.
--stateful	None	Pull using local state tracking, do not overwrite local files with remote changes.
--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.

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
--fail-conflicts	None	Error on conflicts (both remote and local have changes on the same item).
--skip-pull	None	Push without pulling first. Assumes that the pull operation has already been performed.
--yes	None	Push without needing confirmation. The command proceeds automatically without user intervention.
--stateful	None	Push using local state tracking, do not overwrite local files with remote changes.
--plain-secrets	None	Push secrets as plain text. Secrets are uploaded without encryption or obfuscation.
--json	None	Use JSON instead of YAML. The uploaded files are in JSON format instead of YAML.

How stateful mode works

Command	Description
wmill sync pull	Pulls remote changes without using state tracking. Overwrites local files with remote changes.
wmill sync pull --stateful	Pulls remote changes and applies them locally.
wmill sync push	Pushes local changes without using state tracking. Overwrites remote files with local changes.
wmill sync push --stateful	Pushes local changes and applies them remotely.

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: 'bun' # deno is the default, set it to bun if you primarily use bun to avoid needing the .bun.ts extension

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

export interface SyncOptions {
  stateful?: boolean;
  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.