Skip to main content
In this guide, you’ll learn how to route your self-hosted GitHub Actions runner traffic through an HTTP/HTTPS proxy. A proxy server acts as an intermediary, forwarding requests between your runner and the Internet for improved security, privacy, or access to geo-restricted endpoints.
The image shows a GitHub documentation page about configuring a proxy server with self-hosted runners, including instructions on using environment variables.

​
Proxy Configuration Options

You can configure proxy settings for your self-hosted runner in two primary ways:
MethodDescriptionConfiguration Location
Environment VariablesSet HTTPS_PROXY, HTTP_PROXY, and NO_PROXY on the host.Shell profile or CI service
.env FilePlace a .env file in the runner directory with the same vars.Runner install folder

​
1. Environment Variables

On the machine hosting your runner, export:
VariablePurposeExample
HTTPS_PROXYProxy for HTTPS requestshttp://proxy.local:8080
HTTP_PROXYProxy for HTTP requestshttp://username:[email protected]
NO_PROXYHosts or domains to bypass the proxyexample.com,myserver.local:443
export HTTPS_PROXY="http://proxy.local:8080"
export HTTP_PROXY="http://proxy.local:8080"
export NO_PROXY="example.com,myserver.local:443"
NO_PROXY accepts comma-separated hostnames, IP addresses, or domains (optionally with ports).

​
2. .env File

If modifying system environment variables is impractical, create a .env file in the directory where you extracted the runner: 
https_proxy=http://proxy.local:8080
http_proxy=http://proxy.local:8080
no_proxy=example.com,myserver.local:443

​
Docker Containers

For workflows that launch Docker containers, configure Docker’s proxy settings separately.
For example, create or edit /etc/systemd/system/docker.service.d/http-proxy.conf: 
[Service]
Environment="HTTP_PROXY=http://proxy.local:8080" "HTTPS_PROXY=http://proxy.local:8080"
Then reload and restart Docker: 
systemctl daemon-reload
systemctl restart docker

​
Demo: Proxy in a Workflow

The following sample workflow sends external HTTP requests with and without proxy authentication. 
name: Demo Proxy Configuration  
on: workflow_dispatch

jobs:
  demo_job:
    runs-on: self-hosted
    steps:
      - name: Hello
        run: echo "Hello from self-hosted runner!"

      - name: External Call (No Proxy)
        run: curl -v http://httpbin.org/ip

      - name: External Call (Invalid Proxy Credentials)
        run: |
          curl -v \
            -x http://wrong-user:wrong-pass@localhost:3128 \
            http://httpbin.org/ip
The image shows a GitHub Actions page for a repository named "enterprise-actions-demo" with a workflow titled "Exploring Github Enterprise Action Features/Policies." It displays a list of workflow runs with their statuses and details.

​
Logs: No Proxy

$ curl -v http://httpbin.org/ip
* Connected to httpbin.org (3.214.174.72) port 80 (#0)
> GET /ip HTTP/1.1
> Host: httpbin.org
< HTTP/1.1 200 OK
{"origin": "35.188.139.128"}
This request bypasses any proxy and connects directly.

​
Logs: Invalid Proxy Credentials

$ curl -v -x http://wrong-user:wrong-pass@localhost:3128 http://httpbin.org/ip
* Connected to localhost (127.0.0.1) port 3128 (#0)
> GET http://httpbin.org/ip HTTP/1.1
> Proxy-Authorization: Basic e3dyb25nLXVzZXI6d3Jvbmc= 
< HTTP/1.1 407 Proxy Authentication Required
<title>ERROR: Cache Access Denied</title>
The image shows a GitHub Actions job log with an error message indicating an external call failed due to invalid proxy credentials.
Avoid hard-coding credentials in workflows. Instead, store proxy credentials securely on the runner host or via GitHub Secrets.

​
Setting Proxy Variables on the Runner Host

On your VM or bare-metal host, export the proxy variables before launching the runner service: 
export HTTPS_PROXY="http://user:password@localhost:3128"
export HTTP_PROXY="http://user:password@localhost:3128"
export NO_PROXY="example.com,myserver.local:443"
systemctl status squid   # Verify your Squid or other proxy service
The image shows a GitHub documentation page about configuring a proxy server using environment variables for self-hosted runners. It includes examples of proxy URLs and a sidebar with navigation links related to GitHub Actions.
Restart the runner service so it picks up the new environment: 
# Example if using a systemd service
systemctl restart actions.runner.your-repo.service

​
Verifying Proxy Usage in Your Workflow

Update your workflow to print proxy variables and make an HTTPS request: 
name: Verify Proxy Usage  
on: workflow_dispatch

jobs:
  verify_proxy:
    runs-on: self-hosted
    steps:
      - name: Show Proxy Environment
        run: |
          echo "HTTPS_PROXY: $HTTPS_PROXY"
          echo "HTTP_PROXY:  $HTTP_PROXY"
          echo "NO_PROXY:    $NO_PROXY"

      - name: External Call via Proxy
        run: curl -v https://httpbin.org/ip
The image shows a GitHub Actions interface with a completed workflow run named "demo_job," which includes steps like setting up the job, making an external call using cURL, and verifying proxy settings.
Once the run completes:
The image shows a GitHub Actions interface with a completed workflow run titled "Exploring Github Enterprise Action Features/Policies." The workflow includes steps like "Set up job," "Hello," "External Call using cURL," "Verify Proxy Settings," and "Complete job," all marked as successful.

​
Logs: Proxy in Action

* Uses proxy env variable HTTP_PROXY = 'localhost:3128'
* Connected to localhost (127.0.0.1) port 3128 (#0)
> GET https://httpbin.org/ip HTTP/1.1
> Proxy-Authorization: Basic e2VjaGF0ZXpzOnBhc3N3b3JkMQ== 
< HTTP/1.1 200 OK
{"origin": "127.0.0.1, 35.188.139.128"}
The runner picks up the proxy variables automatically, authenticates with your proxy (e.g., Squid), and successfully forwards requests.
Thank you for following this tutorial on setting up proxies for your self-hosted GitHub Actions runners! For more details, see the GitHub Actions documentation.

Watch Video