Skip to main content

​
HTTP/2 protocol downgrade

Symptoms: CLI failures, connection timeouts, protocol errors Cause: Zscaler downgrades HTTP/2 to HTTP/1.1 for SSL-inspected traffic. Fix: Contact your Zscaler admin to enable HTTP/2 for SSL-inspected traffic under Administration > Advanced Settings. See Zscaler docs.
If your organization uses a custom domain, make sure Zscaler preserves HTTP/2 for traffic to the custom management-plane hostname.

​
SSL certificate verification failures

Symptoms: VS Code can’t connect, “certificate verify failed”, untrusted certificate warnings Cause: Zscaler intercepts HTTPS and presents its own certificates. Apps with custom cert stores may not trust them. Check if Zscaler is intercepting:
If your organization uses a custom domain, run this check against the custom management-plane hostname. Also check app.gitpod.io if users authenticate built-in integrations.
If the issuer shows “Zscaler Inc.” instead of the expected certificate issuer, SSL inspection is active. Fix (recommended): Add app.gitpod.io to SSL inspection bypass list.
If your organization uses a custom domain, add the custom management-plane hostname to the SSL inspection bypass list. Browser clients still need access to app.gitpod.io to authenticate built-in integrations.
Alternative for VS Code: Enable “System certificates” in VS Code settings (requires v1.97+). If issues persist, also enable “Electron Fetch” and “System Certificates V2”.

​
Runner connection issues

Symptoms: Runner can’t connect, OAuth failures, “connection refused” errors Cause: Zscaler is blocking the Ona management-plane hostname, OAuth callbacks, or runner-gateway protocols. Fix:
  • Allow outbound HTTPS (TCP 443) to the runner’s configured Ona management-plane hostname (app.gitpod.io by default). Allowlist the hostname rather than the IP addresses it currently resolves to.
  • Ensure WebSocket and gRPC traffic is allowed
  • Workaround: Use Personal Access Tokens instead of OAuth while configuring
If your organization uses a custom domain, allow outbound HTTPS to the custom management-plane hostname used by the runner, not only app.gitpod.io.

​
Configuration checklist

Work with your network team to configure: SSL inspection:
  • Add app.gitpod.io to the bypass list
  • Verify the certificate shows the expected issuer, not “Zscaler”
If your organization uses a custom domain, also add the custom management-plane hostname to the bypass list and verify its certificate issuer.
HTTP/2:
  • Enable HTTP/2 for SSL-inspected traffic in Advanced Settings
If your organization uses a custom domain, confirm this setting applies to traffic for the custom management-plane hostname.
Network:
  • Allow outbound HTTPS (TCP 443) to app.gitpod.io
  • Allow WebSocket and gRPC traffic
If your organization uses a custom domain, also allow outbound HTTPS, WebSocket, and gRPC traffic to the custom management-plane hostname.

​
Verify configuration

If your organization uses a custom domain, replace app.gitpod.io with the custom management-plane hostname in both commands. Test app.gitpod.io separately if users authenticate built-in integrations.
Then test VS Code extension and runner connectivity.

​
Getting help

Collect and share with support:
  • Output of ona network-troubleshoot, run from the machine where the connection to Ona is failing. This tests DNS, TCP, TLS, and authenticated API connectivity. See the CLI reference for details.
  • Output from curl -I -v https://app.gitpod.io
  • Runner support bundle
  • Environment support bundle, if the environment is reachable
  • VS Code / Ona extension logs
  • Network configuration details
If your organization uses a custom domain, include the curl -I -v output for the custom management-plane hostname. Include the output for app.gitpod.io too if built-in integration authentication is affected.