CircleCI Server v3.x Configuring a Proxy
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.
Installation and configuration
There are two stages to installing CircleCI server behind a proxy. First, at the point of installation, the proxy addresses need to be specified, along with any addresses that should not be behind the proxy.
Installing behind a proxy
The installation process is described in detail in the CircleCI Server v3.x Installation guide. Both proxy and non-proxy addresses should be supplied using the arguments described here. The installation command should be in the form:
kubectl kots install circleci-server --http-proxy <my-http-proxy-uri> --https-proxy <my-https-proxy> --no-proxy <my-no-proxy-list>
Configuring your proxy
Once you have installed server and gained access to the management console, there are some fields that need to be completed in the configuration section, as shown in the screenshot below. These fields will not be automatically populated and so the same proxy and no-proxy addresses you supplied during installation will need to be supplied here. If your proxy requires authentication in the form of a username and password check the "HTTP Proxy authenticated" option to add the credentials at this point.
Installing behind a proxy will prevent the use of CircleCI runner.
Some additional configuration will be required to import orbs when installed behiind 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
If your GitHub instance is running outside of the proxied environment (either GitHub.com or GitHub enterprise), you must ensure that SSH traffic from our application (inside the Kubernetes cluster) and from our Nomad node can reach your instance without additional configuration. Our SSH agents do not respect proxy settings because it uses a different network protocol. If a proxy is the only way that any traffic can reach outside the proxied environment this means it will block SSH traffic and our application will fail.
The load balancer endpoints must be added to the no-proxy list for the following services:
vm-service. This is because the no-proxy list is shared between the application and build-agent. The application and build-agent are assumed to be behind the same firewall and therefore cannot have a proxy between them.
The KOTS admin console cannot be upgraded if proxy setting were set. The proxy settings will be deleted and cause the KOTS admin console to break.
If you install server behind a proxy, you may need to provide a custom image for VM service. Visit the CircleCI Linux Image Builder repo for further information.
If object storage is outside the proxy no job features that use object storage will work. This includes:
Cache save and restore
Users can get around this by setting environment variables on their jobs like so:
jobname: docker: - image: ubuntu:latest 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 extremely important that these environment variables are set in this particular location because its the only location that propagates them to the correct service.
Help make this document better
This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.