{"meta":{"title":"Using proxy servers with a runner","intro":"You can configure runners in isolated environments to use a proxy server for secure communication with GitHub.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/actions","title":"GitHub Actions"},{"href":"/en/actions/how-tos","title":"How-tos"},{"href":"/en/actions/how-tos/manage-runners","title":"Manage runners"},{"href":"/en/actions/how-tos/manage-runners/use-proxy-servers","title":"Use proxy servers"}],"documentType":"article"},"body":"# Using proxy servers with a runner\n\nYou can configure runners in isolated environments to use a proxy server for secure communication with GitHub.\n\n## Configuring a proxy for Linux and Windows runners\n\nIf your runner needs to communicate via a proxy server, you can configure proxy settings using environment variables or system-level configurations.\n\n| Variable      | Description                                                                                           | Example                                                                                     |\n| ------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `https_proxy` | Proxy URL for HTTPS traffic. You can include basic authentication if required.                        | `http://proxy.local`<br>`http://192.168.1.1:8080`<br>`http://username:password@proxy.local` |\n| `http_proxy`  | Proxy URL for HTTP traffic. You can include basic authentication if required.                         | `http://proxy.local`<br>`http://192.168.1.1:8080`<br>`http://username:password@proxy.local` |\n| `no_proxy`    | A comma-separated list of hosts or IP addresses that should bypass the proxy. Some clients only honor IP addresses when connections are made directly to the IP rather than a hostname. | `example.com`<br>`example.com,myserver.local:443,example.org`                               |\n\nThe proxy environment variables are read when the runner application starts, so you must set the environment variables before configuring or starting the runner application. If your proxy configuration changes, you must restart the runner application.\n\nOn Windows machines, the proxy environment variable names are case-insensitive. On Linux and macOS machines, we recommend that you use all lowercase environment variables. If you have an environment variable in both lowercase and uppercase on Linux or macOS, for example `https_proxy` and `HTTPS_PROXY`, the self-hosted runner application uses the lowercase environment variable.\n\nThe connection between self-hosted runners and GitHub is over HTTPS (port 443). \n\n> [!WARNING]\n> Self-hosted runners do not support using IP addresses in the `no_proxy` environment variable. If your GitHub Enterprise Server instance uses an IP address and you configure `no_proxy` to bypass the proxy for that address, the runner will still fail to connect.\n> If your GitHub Enterprise Server instance is accessed using an IP address and the connection must bypass the proxy, the runner will fail to connect, even if that IP address is listed in `no_proxy`.\n\n### Example configurations\n\n> [!NOTE]\n> To avoid issues, it's good practice to treat environment variables as case sensitive, irrespective of the behavior of the operating system and shell you are using.\n\n#### Linux and macOS\n\nSet proxy environment variables for your runner.\n\n```shell copy\nexport https_proxy=http://proxy.local:8080\nexport http_proxy=http://proxy.local:8080\nexport no_proxy=example.com,localhost,127.0.0.1\n```\n\n#### Windows\n\nOn Windows, you can configure proxy settings either by setting environment variables or by using the [netsh command](https://learn.microsoft.com/en-us/windows/win32/winhttp/netsh-exe-commands#set-advproxy).\nThe netsh approach applies to applications and services that rely on the WinHTTP API.\n\nSetting environment variables is still required for runners that use private networking. Whether you also need to configure netsh depends on the applications used in your workflows.\n\n```shell copy\nnetsh winhttp set advproxy setting-scope=machine settings={\\\"Proxy\\\":\\\"proxy.local:8080\\\",\\\"ProxyBypass\\\":\\\"168.63.129.16;169.254.169.254\\\",\\\"AutoconfigUrl\\\":\\\"\\\",\\\"AutoDetect\\\":false} \n```\n\nWhen configuring this during custom image generation, use `setting-scope=machine` to ensure the proxy settings persist after reboots and during VM imaging.\n\n### Making proxy settings persistent\n\nWhen setting these environment variables during custom image generation, ensure the configuration persists across reboots or image rebuilds.\n\n#### Linux and macOS\n\nWrite the variables to `/etc/environment`.\n\n```shell\n echo 'http_proxy=http://proxy.local' >> /etc/environment\n```\n\n#### Windows\n\nSet the system-wide environment variables.\n\n```shell copy\n[Environment]::SetEnvironmentVariable(\"http_proxy\", \"http://proxy.local\", \"Machine\")\n```\n\n## Configuring a proxy for Azure runners\n\nIf your runner is hosted in Azure, either as a self-hosted runner or a GitHub-hosted larger runner deployed with private networking, you may need to configure a proxy to allow outbound connectivity to GitHub services while maintaining network isolation.\n\nYou should add Azure metadata and management IPs to your `no_proxy` list to ensure the runner can access required Azure services. These endpoints allow Azure VMs to retrieve configuration and identity information needed for proper operation.\n\nThe two Azure IPs are:\n* 168.63.129.16 (see [Azure IP address 168.63.129.16 overview](https://learn.microsoft.com/en-us/azure/virtual-network/what-is-ip-address-168-63-129-16?tabs=linux))\n* 169.254.169.254 (see [Azure Instance Metadata Service](https://learn.microsoft.com/en-us/azure/virtual-machines/instance-metadata-service?tabs=linux))\n\n## Using a .env file to set the proxy configuration\n\n> [!NOTE]\n> Using a `.env` file to set the proxy configuration cannot be done on a GitHub-hosted runner.\n\nOn self-hosted runners, you can configure proxy settings by adding the variables to a `.env` file in the self-hosted runner application directory (the directory where you downloaded and unpacked the runner software). This approach is useful when the runner is configured to run as a service under a system account. When the runner starts, it reads the variables set in `.env` for the proxy configuration.\n\n### Example `.env` proxy configuration\n\n```shell copy\nhttps_proxy=http://proxy.local:8080\nno_proxy=example.com,myserver.local:443\n```\n\n## Setting proxy configuration for Docker containers\n\nIf you use Docker container actions or service containers in your workflows, you might also need to configure Docker to use your proxy server in addition to setting the above environment variables.\n\nFor information on the required Docker configuration, see [Configure Docker to use a proxy server](https://docs.docker.com/network/proxy/) in the Docker documentation."}