Configure a runner to use a proxy
This support document is only applicable to Linux Docker runners. For shell runners (MacOS, Windows, Linux Shell), the proxy needs to be configured in the runner’s host.
Depending on how your or your organization’s system and workflows are set up, you may need to allow your self-hosted runners to run behind a proxy server. A runner can be configured to operate behind a proxy by passing theHTTP_PROXY andHTTPS_PROXY environment variables through to the Docker run command.
Runners communicate back to Bitbucket over https for git clone and for any REST API calls it makes internally, so at a minimumHTTPS_PROXY must be set.
The example below shows how to start the runner behind a proxy on Linux:
docker container run \ -e HTTP_PROXY="http://my-http-proxy" \ -e HTTPS_PROXY="http://my-https-proxy" \ .... docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-runnerConfigure the host Docker daemon to use a proxy
When using Docker, it may be necessary to also configure the Docker daemon on your runner host to also communicate to the outside world using a proxy. See theDocker documentation for details on how to set this up.
Configure the Docker service to use a proxy
When your build uses the Docker service, it will, by default, use theHTTP_PROXY andHTTPS_PROXY variables passed to the runner.
It is possible to configure the Docker service to use a proxy independently, or with a different proxy than what the Runner uses. This can be done by providing values forHTTP_PROXY andHTTPS_PROXY as workspace or repository variables, or by using acustom Docker-in-Docker service:
services: docker: image: docker:dind environment: HTTP_PROXY: "http://username:password@proxy2.domain.com" HTTPS_PROXY: "http://username:password@proxy2.domain.com"Limitations
HTTP_PROXYandHTTPS_PROXYvariables passed to the runner on start up are not passed through to the build container, service containers, or pipes. You can configurevariables, such as repository level variables, if required.Pushing back usinggit + http without configuring authentication is not supported. To push back over https, you will need to manually configure git to use a proxy as well as configure git to use appropriate credentials, or push back over ssh.
For the Docker service, any
HTTP_PROXYorHTTPS_PROXYpipelines variables configured at the workspace, repository, or service level will override the variables passed to the runner.Proxies requiring authentication are not supported.
Was this helpful?
- Runners
- Set up runners for Windows
- Set up runners for MacOS
Configure a runner to use a proxy
- Configure logging in self-hosted runners
- Configure runner concurrency and inspect step queue