Configure a runner to use a proxy

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 the HTTP_PROXY and HTTPS_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 minimum HTTPS_PROXY must be set.

The example below shows how to start the runner behind a proxy on Linux:

1 2 3 4 5 docker container run \ -e HTTP_PROXY="http://my-http-proxy" \ -e HTTPS_PROXY="http://my-https-proxy" \ ....

Configure 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 the Docker 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 the HTTP_PROXY and HTTPS_PROXY variables passed to the runner.

It is possible to configure the Docker service to use a proxy independently, or with a different proxy that what the Runner uses. This can be done by providing values for HTTP_PROXY and HTTPS_PROXY as workspace or repository variables, or by using a custom Docker-in-Docker service:

1 2 3 4 5 6 services: docker: image: docker:dind environment: HTTP_PROXY: "" HTTPS_PROXY: ""


  • HTTP_PROXY and HTTPS_PROXY variables passed to the runner on start up are not passed through to the build container, service containers, or pipes. You can configure variables, such as repository level variables, if required.

  • Pushing back using git + 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_PROXY or HTTPS_PROXY pipelines variables configured at the workspace, repository, or service level will override the variables passed to the runner.

  • Proxies requiring authentication are not supported.

Additional Help