Git sync
From the workspace settings, you can set a git_repository resource on which the workspace will automatically commit and push scripts, flows and apps to the repository on each deploy.
You can use this feature to Deploy to prod using a git workflow.
For all details on Version control in Windmill, see Version control.
This video shows how to set up a Git repository for a workspace (Git sync - workspace mode).
Git sync - Workspace mode
All scripts, flows and apps located in the workspace will be pushed to the Git repository. You can filter Git sync on path so that only the scripts, flows and apps with a matching path will be pushed to the Git repository. By default, everything in folders will be synced (with rule f/**).
On each deployment, only the updated script/flow/app will be pushed to the remote Git repository.
This feature is Cloud & Enterprise Self-Hosted only.
Note that you can explicitly exclude (or include) specific files or folders to be taken into account with a wmill.yaml file.
Setup
1. Initialize Git repository
First, create a Git repository to store your Windmill workspace:
Option A: Create empty repository (Recommended)
Create an empty Git repository on your Git provider (GitHub, GitLab, etc.) without any initial files. Windmill will populate it automatically in the next step.
Option B: Manual CLI setup
For more control, you can set up the repository manually using the Windmill CLI:
- Use Windmill CLI to pull the workspace locally:
wmill sync pull
Configure your wmill.yaml file with the desired filter settings before pushing to Git.
- Create a Git repository (in the example, on GitHub) and push the initial workspace content:
git init
git remote add origin https://github.com/username/reponame.git
git add .
git commit -m 'Initial commit'
git push -u origin main
You now have your Windmill workspace on a GitHub repository.
2. Setup in Windmill
- Go to workspace settings → Git Sync tab
- Click + Add connection
- Create or select a git_repository resource pointing to your Git repository. You have two authentication options:
- GitHub App: Use the GitHub App for simplified authentication and enhanced security
- Personal Access Token: Use a token with Read-and-write on "Contents". Your URL should be
https://[USERNAME]:[TOKEN]@github.com/[ORG|USER]/[REPO_NAME].git
- Select sync mode (sync mode or promotion mode)
- Complete the configuration of the connection and save
If you chose Option A (empty repository), use the "Initialize Git repository" operation to automatically:
- Create the
wmill.yamlconfiguration file with your filter settings - Push the entire workspace content to the Git repository
If the repository already contains a wmill.yaml file, the settings will be automatically imported and applied to your workspace configuration.
Configuration settings: Git sync filter settings are pulled from the wmill.yaml file in your repository. Once the connection is saved, you can update settings by changing wmill.yaml and pulling the settings via the corresponding button.
Signing commits with GPG
If your repo requires signed commits, you can set up GPG on your Windmill instance.
- Generate a GPG key pair:
gpg --full-generate-key
- Add the key to your GithHub account:
gpg --armor --export <key_id>
Go to your GitHub account settings => "SSH and GPG keys" and add the GPG public key.
- Add the private key to your Windmill instance:
gpg --armor --export-keys <key_id>
In the Windmill workspace "Git Sync" settings, edit the "GPG key" field with the GPG private key. Use the email address associated with the key and set the passphrase if you added one.
Make sure to double check that the email address associated with the key is the same as the one you use to commit to the repo. Furthermore, double check that the key id is the same as the one you see in the "GPG key" field on your GitHub account.
All commits will now be signed and commited as the user matching the email address associated with the key.
Azure DevOps with Service Principal setup
In Microsoft Entra ID, create an application and a secret (also known as Service Principal - an identity used by applications to access Azure resources).
Create an azure resource on your Windmill instance with the application's client_id, client_secret and tenant_id.
On Azure DevOps, add the application to the DevOps organization with the appropriate permissions.
In Git sync settings of your Windmill instance, define a new repository with URL:
https://AZURE_DEVOPS_TOKEN(<path_to_the_azure_resource>)@dev.azure.com/<organization>/<project>/_git/<repository>
Filters
Path filters
Only scripts, flows and apps with their path matching one of the set filters will be synced to the Git repositories below. The filters allow *' and **' characters, with *' matching any character allowed in paths until the next slash (/) and **' matching anything including slashes.
By default everything in folders (with rule f/**) will be synced.
You can configure:
- Include paths: Primary patterns for what to sync (e.g.,
f/**) - Exclude paths: Patterns to exclude after include checks
Type filters
On top of the filter path above, you can include only certain type of object to be synced with the Git repository. By default everything is synced.
You can filter on:
- Scripts - Individual scripts
- Flows - Workflow definitions
- Apps - Application definitions
- Folders - Folder structure
- Resources - Resource instances
- Variables - Workspace variables
- Include secrets - Option to include secret variables
- Schedules - Scheduled job definitions
- Resource types
- Users - User definitions
- Groups - Group definitions
- Triggers - Event triggers (HTTP routes, WebSocket, Postgres, Kafka, NATS, SQS, GCP Pub/Sub, MQTT)
- Workspace settings - Global workspace configuration
- Encryption key - Workspace encryption key
Repositories to sync
The changes will be deployed to all the repositories set in the Git sync settings.
Sync modes
You can choose between two sync modes for each repository:
Sync mode (default)
Changes are committed directly to the branch specified in the git_repository resource. This is the standard mode for simple workspace synchronization.
Promotion mode
Windmill will create branches per deployed object based on its path, prefixed with 'wm_deploy/'. This enables advanced deployment workflows with pull requests and code review processes.
When promotion mode is enabled, you can choose to:
- Create one branch per deployed object (default)
- Group deployed objects by folder: Create a branch per folder containing objects being deployed instead
You can configure promotion-specific sync behavior using promotionOverrides in your wmill.yaml file. This allows different filter settings when promoting changes to specific branches.
This promotion mode is used to deploy to a prod workspace using a git workflow.
Repository operations
Each configured repository supports several operations:
- Test connection: Verify repository access and credentials
- Preview changes: Perform a dry-run to see what would be synced
- Push to repository: Send workspace content to git repository
- Pull from repository: Get changes from git repository to workspace
- Pull settings: Get only wmill.yaml configuration changes
- Initialize repository: Set up new git repository with Windmill structure
wmill.yaml integration
Git sync settings can be controlled via the wmill.yaml file in your repository root. This enables:
- CLI compatibility: Settings configured in the UI are compatible with Windmill CLI
- Version-controlled configuration: Your sync settings are stored in git alongside your code
- Branch-specific overrides: Different sync behavior per git branch
- Promotion-specific settings: Special configuration for deployment workflows
The frontend will detect existing wmill.yaml files and merge settings appropriately.
Exclude specific types for this repository only
You can exclude specific types per repository, overriding the global workspace filters.
Git sync - Item mode: Deploy to prod using a git workflow
This feature can be used alongside GiHub Actions to adopt a robust development process for your Windmill scripts, flows and apps, with for example a Staging Workspace making automatically PRs on a repo that pushes to a Prod workspace upon merge.
More details at: