Configuring a proxy for Linux and Windows runners
If your runner needs to communicate via a proxy server, you can configure proxy settings using environment variables or system-level configurations.
| Variable | Description | Example |
|---|---|---|
https_proxy | Proxy URL for HTTPS traffic. You can include basic authentication if required. | http://proxy.localhttp://192.168.1.1:8080http://username:password@proxy.local |
http_proxy | Proxy URL for HTTP traffic. You can include basic authentication if required. | http://proxy.localhttp://192.168.1.1:8080http://username:password@proxy.local |
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.comexample.com,myserver.local:443,example.org |
The 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.
On 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.
The connection between self-hosted runners and GitHub is over HTTPS (port 443).
Example configurations
Note
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.
Linux and macOS
Set proxy environment variables for your runner.
export https_proxy=http://proxy.local:8080 export http_proxy=http://proxy.local:8080 export no_proxy=example.com,localhost,127.0.0.1
export https_proxy=http://proxy.local:8080 export http_proxy=http://proxy.local:8080 export no_proxy=example.com,localhost,127.0.0.1 Windows
On Windows, you can configure proxy settings either by setting environment variables or by using the netsh command. The netsh approach applies to applications and services that rely on the WinHTTP API.
Setting 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.
netsh winhttp set advproxy setting-scope=machine settings={\"Proxy\":\"proxy.local:8080\",\"ProxyBypass\":\"168.63.129.16;169.254.169.254\",\"AutoconfigUrl\":\"\",\"AutoDetect\":false} netsh winhttp set advproxy setting-scope=machine settings={\"Proxy\":\"proxy.local:8080\",\"ProxyBypass\":\"168.63.129.16;169.254.169.254\",\"AutoconfigUrl\":\"\",\"AutoDetect\":false} When configuring this during custom image generation, use setting-scope=machine to ensure the proxy settings persist after reboots and during VM imaging.
Making proxy settings persistent
When setting these environment variables during custom image generation, ensure the configuration persists across reboots or image rebuilds.
Linux and macOS
Write the variables to /etc/environment.
echo 'http_proxy=http://proxy.local' >> /etc/environment Windows
Set the system-wide environment variables.
[Environment]::SetEnvironmentVariable("http_proxy", "http://proxy.local", "Machine") [Environment]::SetEnvironmentVariable("http_proxy", "http://proxy.local", "Machine") Configuring a proxy for Azure runners
If 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.
You 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.
The two Azure IPs are:
- 168.63.129.16 (see Azure IP address 168.63.129.16 overview)
- 169.254.169.254 (see Azure Instance Metadata Service)
Using a .env file to set the proxy configuration
Note
Using a .env file to set the proxy configuration cannot be done on a GitHub-hosted runner.
On 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.
Example .env proxy configuration
https_proxy=http://proxy.local:8080 no_proxy=example.com,myserver.local:443
https_proxy=http://proxy.local:8080 no_proxy=example.com,myserver.local:443 Setting proxy configuration for Docker containers
If 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.
For information on the required Docker configuration, see Configure Docker to use a proxy server in the Docker documentation.