Installing server behind a proxy
On This Page
Depending on your security requirements, you might want to install CircleCI server behind a proxy. Installing behind a proxy gives you the power to monitor and control access between your installation and the broader Internet.
Configuring a proxy happens during Phase 2 - Core services.
Known limitations
-
Some additional configuration is required to import orbs when installed behind a proxy. See Orbs on server docs for more information.
-
The JVM only accepts proxies that run over HTTP, not HTTPS, and therefore proxy URIs must be of the form
http://user:password@host:port
rather thanhttps://user:password@host:port
. -
If your GitHub instance is running outside of the proxied environment (either GitHub.com or GitHub Enterprise), you must ensure that SSH traffic from CircleCI (inside the Kubernetes cluster) and from our Nomad node can reach your instance. The default
checkout
step in a CircleCI job will fail to clone code and ourssh-keyscan
of GitHub Enterprise will not work. While you may configure an SSH proxy,ssh-keyscan
can NOT be proxied and instead will require you providegithub.fingerprint
when using GHE. -
If you install server behind a proxy, you may need to provide a custom image for machine provisioner. Visit the CircleCI Linux Image Builder repository for further information.
-
If object storage is outside the proxy, no job features that use object storage will work. This includes:
-
Artifacts
-
Test results
-
Cache save and restore
-
Workspaces
Users can get around this restriction by setting environment variables on their jobs. For example:
jobs: my-job: docker: - image: cimg/node:17.2.0 environment: HTTP_PROXY: http://proxy.example.com:3128 HTTPS_PROXY: http://proxy.example.com:3128 NO_PROXY: whatever.internal,10.0.1.2
It is crucial that these environment variables are set in this specific location because it is the only location that propagates them to the correct service.
-