Gitpod self-hosted behind an internal CA: cluster-level CA bundle vs per-workspace trust configuration

Answer first

In recent self-hosted releases, the installation-level custom CA setting covers the Gitpod control plane and ingress proxy only. It does not automatically populate the system trust store inside workspace containers. The dashboard and workspace launcher can validate the internal CA, but HTTPS operations inside the workspace terminal will fail unless the CA is made available to each runtime.

Version assumption: configuration key changed from gitpod.customCA in v2025.3 to gitpod.custom_ca in v2026.1. The mounted CA path and environment variable names also vary by version.

What the installation setting actually covers

• Control plane components and ingress proxy trust the custom CA for inbound traffic.
• Workspace containers do not inherit the CA into /etc/ssl/certs by default.
• Gitpod may expose the CA file via a mount and an env var, e.g. $GITPOD_CUSTOM_CA, but runtimes must be pointed to it explicitly.

Per-runtime vs image rebuild

The supported approach for workspace tooling is per-runtime configuration, not rebuilding images for every base.

• Node.js: set NODE_EXTRA_CA_CERTS to the CA file. This is the documented way to extend trust.
• Java: import the CA into the JDK cacerts or run with JAVA_OPTS pointing to a trust store. Rebuilding is a clean but heavier option.
• Git: use GIT_SSL_CAINFO or http.sslCAinfo.
• Go/Rust/etc: use SSL_CERT_FILE or equivalent flags.

Rebuild the workspace image with the CA bundled only if a runtime has no external CA option or you need an immutable image for all teams. Per-runtime variables are preferred when teams use diverse base images and CA rotation is expected.

Verify inside a fresh workspace

1. Check system store presence:

   grep -i "Internal CA" /etc/ssl/certs/ca-certificates.crt || echo "not in system store"

2. Check runtime env:

   node -e "console.log(process.env.NODE_EXTRA_CA_CERTS)"

3. Test TLS to an internal host:

   openssl s_client -connect internal.repo:443 -showcerts < /dev/null | grep -A1 "issuer"

4. Java check:

   keytool -list -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit | grep "Internal CA"

If failures persist after per-runtime setup, the one diagnostic that changes the recommendation is the exact Gitpod self-hosted version you are running, as it determines the correct config key and CA mount path.