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.
The CircleCI hostname must be added to the no-proxy list because the following services:
vm-service. The application and build-agent share a no-proxy list and are assumed to be behind the same firewall and therefore cannot have a proxy between them.
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 CircleCI (inside the Kubernetes cluster) and from our Nomad node can reach your instance. Please note the default
checkoutstep in a CircleCI job will fail to clone code and our
ssh-keyscanof GitHub Enterprise will not work. While you may configure an SSH proxy,
ssh-keyscancan NOT be proxied and instead will require you provide
github.fingerprintwhen using GHE.
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:
jobs: my-job: docker: - image: cimg/node:17.2.0 auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference 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 guidefirst).
- 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.