From 025128dac8e61dab6d24454d730e4a9a0f45aa0f Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Fri, 6 Feb 2026 13:04:21 +0100 Subject: [PATCH] Add workaround for `http` CSP configuration for WebKit browsers. WebKit's security mechanisms block HTTP requests from applications, preventing GitButler from connecting to self-hosted instances over plain HTTP even with correct CSP configuration. Document using Caddy as a local HTTPS reverse proxy as a workaround. Based on: https://github.com/gitbutlerapp/gitbutler/issues/12242#issuecomment-3859589256 Co-authored-by: nshcr <104677079+nshcr@users.noreply.github.com> Co-authored-by: Claude --- content/docs/troubleshooting/custom-csp.mdx | 47 ++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/content/docs/troubleshooting/custom-csp.mdx b/content/docs/troubleshooting/custom-csp.mdx index de8f92e..9095aff 100644 --- a/content/docs/troubleshooting/custom-csp.mdx +++ b/content/docs/troubleshooting/custom-csp.mdx @@ -3,6 +3,7 @@ title: Custom Content Security Policy (CSP) description: Configure custom Content Security Policy settings to allow GitButler connections to self-hosted GitHub, GitLab, or Ollama instances. --- +import { Callout } from 'fumadocs-ui/components/callout'; import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; By default GitButler uses a strict Content Security Policy (CSP) to protect against various attacks, such as cross-site scripting (XSS) and data injection attacks. This policy restricts the sources from which content can be loaded, as well as the hosts the application can connect to, ensuring that only trusted sources are allowed. @@ -62,4 +63,48 @@ Note that if `extraCsp` is the only entry in the JSON file, you may want to encl } ``` -The changes will take effect the next time you start GitButler. \ No newline at end of file +The changes will take effect the next time you start GitButler. + +## Connecting to HTTP instances + +If you are trying to connect to a self-hosted instance served over plain HTTP, you may find that GitButler cannot reach it even with the correct CSP configuration. This is because WebKit (used by GitButler on macOS) blocks insecure HTTP requests from applications. Other platforms may exhibit similar behavior depending on their WebView implementation. + + + This only affects instances served over plain HTTP. If your self-hosted instance already uses HTTPS, you can skip this section. + + +As a workaround, you can run a local HTTPS reverse proxy using [Caddy](https://caddyserver.com). Caddy automatically generates a locally-trusted TLS certificate, so GitButler sees a secure connection while your self-hosted instance continues to run over HTTP. + +### Setting up Caddy as a local HTTPS proxy + +The following example uses [Homebrew](https://brew.sh) on macOS, but the same approach works on any platform where Caddy is available. + +1. Install Caddy: + +```sh +brew install caddy +``` + +2. Create a `Caddyfile` (for example in `~/.config/caddy/Caddyfile`): + +```caddyfile +https://127.0.0.1:PORT { + tls internal + + reverse_proxy http://YOUR_INSTANCE:PORT { + header_up Host YOUR_INSTANCE_HOSTNAME + } +} +``` + +Replace `YOUR_INSTANCE` and `PORT` with the hostname and port of your self-hosted instance. The `header_up Host` directive ensures the original `Host` header is forwarded correctly. + +3. Start Caddy: + +```sh +caddy run --config ~/.config/caddy/Caddyfile +``` + +4. In GitButler, set your forge URL to `https://127.0.0.1:PORT` (matching the port from your Caddyfile) instead of the original HTTP URL. + +Your self-hosted instance should now be accessible through the local HTTPS proxy.