Git integration
Git is a distributed version control system designed to handle everything from small to very large projects with speed and efficiency.
Windmill has a dedicated resource Type used for Git sync, to sync Windmill workspace to a remote repository that will automatically be committed and pushed scripts, flows and apps on each deploy.
More:
This video shows how to set up a Git repository for a workspace.
GitHub App
Instead of using a long lived personal access token to authenticate with GitHub for Git sync, you can use the GitHub App to authenticate with GitHub. This allows you to control which repositories can be accessed by your Windmill deployment using a short-live GitHub app installation token.
GitHub App is available under Windmill Enterprise.
Network requirements
The GitHub App feature requires your Windmill instance to communicate with https://stats.windmill.dev to obtain GitHub installation tokens. This is the same endpoint used for telemetry.
If your GitHub organization uses IP allow lists, you will need to whitelist the IP address of stats.windmill.dev to allow it to request installation tokens from GitHub on behalf of your Windmill instance. Contact support@windmill.dev to get the current IP address.
This network requirement only applies to the Windmill-managed GitHub App. If you use a self-managed GitHub App, your Windmill instance communicates directly with your GitHub instance. In that case, if your GitHub organization uses IP allow lists, whitelist your Windmill instance's IP address instead.
As a Windmill workspace admin, you can install the GitHub app to multiple organizations and link them to your Windmill workspaces. Once an app has been installed to a workspace, you can install it to other workspace where you have the admin role.
You will only be able to use the installation token for Git sync.
GitHub App permissions
Beyond repository contents (read and write), which powers the push direction of Git sync, the GitHub App requests the following permissions to handle the Git to Windmill direction in-app:
| Permission (read and write) | What it enables |
|---|---|
| Repository webhooks | Register a webhook per synced repository so commits deploy to your Windmill workspace instantly (automatic sync from Git) |
| Pull requests | Open pull requests for branches Windmill pushes (promotion wm_deploy/** and fork wm-fork/** branches, see in-app pull request creation) and maintain a deploy-preview comment on your pull requests |
| Checks | Post a "Windmill diff" check on pull requests showing what merging would deploy, and a deploy status check on synced commits |
All of these features are opt-in from the workspace Git sync settings. If your organization has not approved the permissions yet, every feature degrades gracefully: automatic sync falls back to polling and upgrades to webhooks automatically once the webhooks permission is granted, and a failed pull request creation is surfaced on the repository card.
For self-managed GitHub Apps, grant the same permissions in your app settings (Settings → Developer settings → GitHub Apps → Permissions & events) and accept the permission update on the installation. Windmill creates the webhooks per repository itself, so the app-level "Subscribe to events" list needs no changes.
Importing / Exporting to/from other windmill instance
A GitHub app can only be installed to a GitHub organization once. Hence to associate an installation to multiple windmill instances you need to export the associated JWT token on the source instance using the "Export" button and paste the JWT in the destination instance to import the installation.
The JWT token associated to your GitHub app installation is sensitive and has the rights to request a short lived installation token. To revoke the JWT, you need to uninstall the GitHub app from your organization and re-install it to re-associate it with a windmill instance.
Self-managed GitHub App
Instead of using the Windmill-managed GitHub App, you can register your own GitHub App on any GitHub instance — whether GitHub.com or a GitHub Enterprise Server (GHES) instance. This gives you full control over the app configuration and removes the dependency on stats.windmill.dev, as tokens are exchanged directly between your Windmill instance and your GitHub instance.
This feature is Enterprise Edition only and is configured at the instance level by a superadmin.
To set up a self-managed GitHub App:
- Register a new GitHub App on your GitHub instance (github.com or your GHES instance)
- In Windmill Instance Settings, go to Advanced > GitHub Enterprise App and enable "Self-managed GitHub App (for GHES or custom GitHub App)"
- Fill in the app details: Base URL (e.g.
https://github.comor your GHES URL), App ID, App Slug, Client ID, and Private Key (PEM) - Install the GitHub App to your organization on your GitHub instance
Once configured, the self-managed GitHub App can be used for Git sync authentication in the same way as the managed GitHub App. Host-based installation filtering ensures tokens are scoped to the correct GitHub instance, preventing token leakage across instances.
