diff --git a/changelog/2026-03-13-github-enterprise-app/ghes_app_settings.png b/changelog/2026-03-13-github-enterprise-app/ghes_app_settings.png new file mode 100644 index 000000000..dc4bf3370 Binary files /dev/null and b/changelog/2026-03-13-github-enterprise-app/ghes_app_settings.png differ diff --git a/changelog/2026-03-13-github-enterprise-app/ghes_app_settings.png.webp b/changelog/2026-03-13-github-enterprise-app/ghes_app_settings.png.webp new file mode 100644 index 000000000..32694adeb Binary files /dev/null and b/changelog/2026-03-13-github-enterprise-app/ghes_app_settings.png.webp differ diff --git a/changelog/2026-03-13-github-enterprise-app/index.md b/changelog/2026-03-13-github-enterprise-app/index.md new file mode 100644 index 000000000..32a075ae5 --- /dev/null +++ b/changelog/2026-03-13-github-enterprise-app/index.md @@ -0,0 +1,12 @@ +--- +slug: github-enterprise-app +title: GitHub Enterprise Server app support +tags: ['Git Sync', 'Enterprise'] +image: ./ghes_app_settings.png +description: Self-managed GitHub App support for GitHub Enterprise Server instances, enabling Git sync without relying on the Windmill-managed GitHub App. +features: + - 'Register your own GitHub App on GitHub Enterprise Server for Git sync authentication.' + - 'Self-managed JWT token generation and exchange directly with your GHES instance.' + - 'Host-based installation filtering prevents token leakage across GitHub instances.' +docs: /docs/integrations/git_repository#github-enterprise-server +--- diff --git a/docs/advanced/11_git_sync/index.mdx b/docs/advanced/11_git_sync/index.mdx index df4bb491c..9be49fb92 100644 --- a/docs/advanced/11_git_sync/index.mdx +++ b/docs/advanced/11_git_sync/index.mdx @@ -76,6 +76,7 @@ You now have your Windmill workspace on a GitHub repository. 2. Click **+ Add connection** 3. Create or select a [git_repository](../../integrations/git_repository.mdx) resource pointing to your Git repository. You have two authentication options: - **GitHub App**: Use the [GitHub App](../../integrations/git_repository.mdx#github-app) for simplified authentication and enhanced security + - **GitHub Enterprise Server App**: Use a [self-managed GitHub App](../../integrations/git_repository.mdx#github-enterprise-server) for GHES or custom GitHub instances (Enterprise only) - **Personal Access Token**: Use a [token](https://github.com/settings/tokens) with Read-and-write on "Contents". Your URL should be `https://[USERNAME]:[TOKEN]@github.com/[ORG|USER]/[REPO_NAME].git` 4. Complete the configuration of the connection and save diff --git a/docs/advanced/18_instance_settings/index.mdx b/docs/advanced/18_instance_settings/index.mdx index 5d253d012..8b79b1fe8 100644 --- a/docs/advanced/18_instance_settings/index.mdx +++ b/docs/advanced/18_instance_settings/index.mdx @@ -519,3 +519,19 @@ When minimal telemetry is disabled, the following is also collected: - job usage (language, total duration, count) You can "Send usage" to manually send usage data to Windmill and monitor it from the [Customer portal](../../misc/7_plans_details/index.mdx#windmill-customer-portal). You can also "Download usage" to get an encrypted copy of the telemetry data as a `.enc` file. This is useful for air-gapped instances that cannot send telemetry directly — the encrypted file can be sent manually to Windmill. + +## GitHub Enterprise App + +Configure a self-managed GitHub App for GitHub Enterprise Server (or any self-hosted GitHub instance) to enable [Git sync](../11_git_sync/index.mdx) without relying on the Windmill-managed GitHub App via `stats.windmill.dev`. + +This setting is found under **Advanced > GitHub Enterprise App** in Instance Settings and is only available on [Enterprise Edition](/pricing). + +| Field | Description | +|-------|-------------| +| Base URL | The base URL of your GitHub Enterprise Server instance | +| App ID | The ID of your registered GitHub App | +| App Slug | The slug of your GitHub App | +| Client ID | The client ID of your GitHub App | +| Private Key (PEM) | The private key generated for your GitHub App | + +For setup instructions, see [GitHub Enterprise Server](../../integrations/git_repository.mdx#github-enterprise-server). diff --git a/docs/integrations/ghes_app_settings.png b/docs/integrations/ghes_app_settings.png new file mode 100644 index 000000000..dc4bf3370 Binary files /dev/null and b/docs/integrations/ghes_app_settings.png differ diff --git a/docs/integrations/ghes_app_settings.png.webp b/docs/integrations/ghes_app_settings.png.webp new file mode 100644 index 000000000..32694adeb Binary files /dev/null and b/docs/integrations/ghes_app_settings.png.webp differ diff --git a/docs/integrations/git_repository.mdx b/docs/integrations/git_repository.mdx index a5ac36b96..5aa07cf57 100644 --- a/docs/integrations/git_repository.mdx +++ b/docs/integrations/git_repository.mdx @@ -66,3 +66,20 @@ The JWT token associated to your GitHub app installation is sensitive and has th controls src="/videos/github_app_installation.mp4" /> + +### GitHub Enterprise Server + +Organizations using GitHub Enterprise Server (or any self-hosted GitHub instance) can register their own GitHub App instead of using the Windmill-managed one. This removes the dependency on `stats.windmill.dev` — tokens are exchanged directly with your GHES instance using self-managed JWT token generation. + +This feature is [Enterprise Edition](/pricing) only and is configured at the instance level by a [superadmin](../core_concepts/16_roles_and_permissions/index.mdx#superadmin). + +To set up a self-managed GitHub App for GHES: + +1. Register a new GitHub App on your GitHub Enterprise Server instance +2. In Windmill [Instance Settings](../advanced/18_instance_settings/index.mdx#github-enterprise-app), go to **Advanced > GitHub Enterprise App** and enable "Self-managed GitHub App (for GHES or custom GitHub App)" +3. Fill in the app details: Base URL, App ID, App Slug, Client ID, and Private Key (PEM) +4. Install the GitHub App to your organization on your GHES instance + +Once configured, the GHES GitHub App can be used for [Git sync](../advanced/11_git_sync/index.mdx) 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. + +![GitHub Enterprise App settings](./ghes_app_settings.png.webp)