CircleCI Server v3.x Configuring 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.
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 format:
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 accessed 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, 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.
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
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 your 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 configured. 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 restriction by setting environment variables on their jobs. For example:
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 crucial that these environment variables are set in this specific location because it is 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.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.