Skip to content
GProxy
Sign up
Guides 6 Connection Type: 4 views

Proxy Setup in GitHub Actions and CI/CD

This guide details how to effectively set up and manage proxy configurations within your GitHub Actions and CI/CD pipelines using GProxy.

Proxy setup in GitHub Actions and CI/CD involves configuring standard proxy environment variables such as HTTP_PROXY, HTTPS_PROXY, and NO_PROXY within your workflow definition, typically at the job or step level. This enables actions, scripts, and tools executed within the CI/CD pipeline to route their network traffic through a specified proxy server.

Organizations often deploy proxy servers to control outbound network access, enforce security policies, filter content, and cache frequently accessed resources. For CI/CD pipelines operating within such environments, configuring proxy settings is essential to allow build tools, dependency managers, and test scripts to reach external services, package repositories, or APIs. GitHub Actions runners, particularly self-hosted runners, may require proxy configuration to access GitHub itself or other internet resources.

Setting Proxy Environment Variables

The most common and universally recognized method for configuring a proxy in a Linux-based environment (which GitHub-hosted runners primarily use) is through environment variables.

  • HTTP_PROXY: Specifies the proxy server for HTTP requests.
  • HTTPS_PROXY: Specifies the proxy server for HTTPS requests.
  • NO_PROXY: A comma-separated list of hostnames, domains, or IP addresses that should bypass the proxy. This is critical for accessing internal resources directly.

The format for HTTP_PROXY and HTTPS_PROXY is typically http://[user:password@]host:port.
Both uppercase (HTTP_PROXY) and lowercase (http_proxy) versions of these variables are often respected by various tools; using uppercase is standard practice for environment variables.

Workflow-Level Proxy Configuration

Applying proxy settings at the job level ensures that all steps within that job inherit the configuration.

name: CI with Proxy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com,github.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Node.js dependencies
        run: npm install

      - name: Download a file via curl
        run: curl -v https://api.example.com/data

      - name: Access internal service (bypasses proxy)
        run: curl -v http://internal-service.internal.company.com/status

Step-Level Proxy Configuration

For scenarios requiring different proxy settings for specific steps, or to override job-level settings, environment variables can be defined at the step level.

name: CI with Specific Step Proxy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env: # Default proxy for the job (if any)
      HTTP_PROXY: http://default-proxy:8080
      HTTPS_PROXY: http://default-proxy:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Step using default proxy
        run: curl https://external-api.com/v1

      - name: Step using a different proxy
        env:
          HTTP_PROXY: http://special-proxy:3128
          HTTPS_PROXY: http://special-proxy:3128
          NO_PROXY: localhost,127.0.0.1,api.special-domain.com
        run: curl https://api.special-domain.com/v2

Proxy Authentication with Secrets

If your proxy requires authentication, include the username and password directly in the proxy URL. For security, store credentials as GitHub Actions secrets and reference them in the workflow.

First, create repository secrets (e.g., PROXY_USER, PROXY_PASS) in your GitHub repository settings.

name: Authenticated Proxy Workflow
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      HTTPS_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Perform network operation
        run: npm install # or curl, etc.

Common Tools and Proxy Interaction

While HTTP_PROXY and HTTPS_PROXY are widely respected, some tools offer specific configuration methods.

git commands

git generally honors HTTP_PROXY and HTTPS_PROXY for remote operations. For explicit configuration or in cases where environment variables are insufficient, git config can be used.

# Set proxy for HTTP and HTTPS git operations
git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy http://proxy.example.com:8080

# Configure a specific proxy for a particular remote
git config http.https://github.com/.proxy http://github-proxy:8080

npm, yarn

Node.js package managers like npm and yarn respect HTTP_PROXY and HTTPS_PROXY environment variables. They also provide their own configuration commands for persistent settings.

# Using npm config
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080
npm config set no-proxy localhost,127.0.0.1,.internal.com

# Using yarn config
yarn config set proxy http://proxy.example.com:8080
yarn config set httpsProxy http://proxy.example.com:8080
yarn config set no-proxy localhost,127.0.0.1,.internal.com

docker (Image Build and Container Runtime)

Proxy settings for Docker require specific handling for both image build-time and container run-time.

Docker Build-Time Proxy

For commands executed during a docker build (e.g., RUN apk add, RUN apt-get update), proxy settings must be passed as build arguments.

Dockerfile example:

FROM alpine:latest

# Define build arguments for proxy settings
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Set environment variables for subsequent RUN commands
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

# Example: Use proxy for package installation
RUN apk add --no-cache curl

# ... rest of your Dockerfile

GitHub Actions workflow step:

- name: Build Docker image with proxy
  run: |
    docker build . \
      --build-arg HTTP_PROXY=${{ env.HTTP_PROXY }} \
      --build-arg HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      --build-arg NO_PROXY=${{ env.NO_PROXY }} \
      -t my-app:latest

Docker Container Run-Time Proxy

If your workflow runs a Docker container (e.g., using the container: key or docker run), proxy settings must be passed as environment variables to the container.

Using container: key:

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: my-custom-image:latest
      env:
        HTTP_PROXY: ${{ env.HTTP_PROXY }}
        HTTPS_PROXY: ${{ env.HTTPS_PROXY }}
        NO_PROXY: ${{ env.NO_PROXY }}
    steps:
      - name: Run command inside container
        run: curl https://external-api.com/data

Using docker run in a step:

- name: Run Docker container with proxy
  run: |
    docker run \
      -e HTTP_PROXY=${{ env.HTTP_PROXY }} \
      -e HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      -e NO_PROXY=${{ env.NO_PROXY }} \
      my-app:latest /app/script.sh

Java Applications (Maven, Gradle)

Java applications, including build tools like Maven and Gradle, typically require proxy settings to be passed as Java system properties. This is commonly done via MAVEN_OPTS or _JAVA_OPTIONS environment variables.

# For Maven
export MAVEN_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

# For Gradle (also applies to other JVM-based tools)
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

Alternatively, Maven can be configured via ~/.m2/settings.xml, and Gradle via gradle.properties in the project or user home directory.

Troubleshooting Proxy Issues

  • Verify Environment Variables: Use run: env | grep -i proxy in a step to confirm that the proxy environment variables are correctly set and visible to the runner's shell.
  • Check NO_PROXY: Ensure that any internal hosts or GitHub domains are correctly listed in NO_PROXY to prevent unnecessary proxying or routing issues.
  • Proxy Server Logs: If possible, check the proxy server logs for connection attempts from the GitHub Actions runner's IP address. This helps determine if the request is reaching the proxy and why it might be rejected (e.g., authentication failure, access denied).
  • Network Connectivity: Use curl -v --proxy <your-proxy-url> <target-url> from within a workflow step to explicitly test connectivity through the proxy to a known external endpoint.
  • SSL/TLS Certificate Issues: If you are using an HTTPS proxy or accessing HTTPS sites through an HTTP proxy, and the proxy performs SSL inspection, the runner might encounter certificate validation errors. This requires the proxy's root CA certificate to be added to the runner's trust store. This is a complex configuration often managed by self-hosted runner setups.

Proxy Configuration Summary

Tool/Context Primary Proxy Configuration Method(s) Notes
General Shell Commands HTTP_PROXY, HTTPS_PROXY, NO_PROXY environment variables Standard and widely respected by tools like curl, wget, apt, yum. Case-insensitive support for http_proxy is common.
git HTTP_PROXY, HTTPS_PROXY environment variables; git config git config sets a persistent configuration, useful for specific git behaviors or when environment variables are not consistently applied.
npm, yarn HTTP_PROXY, HTTPS_PROXY environment variables; npm config set Environment variables are often sufficient. Tool-specific config commands persist settings or override environment variables.
docker build --build-arg HTTP_PROXY flags in docker build; ARG/ENV in Dockerfile Requires explicit passing of proxy settings as build arguments to be available inside the Docker build context. ENV makes them available to subsequent RUN commands.
docker run (container runtime) -e HTTP_PROXY flags in docker run; env in workflow container: definition Passes proxy environment variables into the running container. This applies when the workflow itself runs a container for its job or step.
Java Applications (Maven, Gradle) _JAVA_OPTIONS, MAVEN_OPTS environment variables with -Dhttp.proxyHost Java applications require specific system properties to configure their HTTP client. These can be set via environment variables that are picked up by the JVM. Alternatively, tool-specific configuration files can be used.
Auto-update: 03.03.2026
All Categories

Advantages of our proxies

25,000+ proxies from 120+ countries

Unlimited Proxies Residential Proxies