Proxies for GitHub and npm: How to Access Repositories and Packages from Countries Where GitHub is Blocked or Slow

GitHub is blocked, has a delay of 10–30 seconds, or npm install hangs halfway — a familiar situation for developers from Russia, Iran, China, and several other countries. There is a solution, and it is simpler than it seems: a properly configured proxy provides stable access to repositories, packages, and the GitHub API without a VPN and without unnecessary complications.

Why GitHub and npm are Blocked or Slowed

Before setting up a proxy, it is important to understand what exactly you are facing. Access issues with GitHub and npm can be of three types, each requiring its own approach.

Complete Blockage at the State Level

A number of countries — China, Iran, North Korea, and since 2022, periodically Russia — block GitHub at the DNS or IP level. This means that requests to github.com either do not go through at all or return a connection error. The npm registry (registry.npmjs.org) may work fine — or may also be blocked.

Corporate Firewalls and Network Restrictions

Even without state blockage, corporate networks often restrict access to external repositories. This is standard practice in banks, government structures, and large enterprises: the IT department blocks outgoing connections on port 443 or blocks specific domains. A developer in such a network cannot perform git clone or npm install without a workaround.

Slow Speed Due to Geography

Technically, GitHub is accessible, but cloning a 500 MB repository takes 40 minutes, and installing dependencies via npm takes forever. This is a routing problem: packages go through overloaded nodes or long routes. A proxy server located in the USA or Europe shortens the path and provides a real speed increase of 3–10 times.

Proxy vs VPN: What to Choose for Working with Code

Many developers instinctively reach for a VPN. This is understandable — a VPN is easy to set up and works immediately for the entire system. However, for working with GitHub and npm, a proxy is often more convenient. Let's break down the difference.

The conclusion is simple: if your task is to give the team access to GitHub and npm, a proxy is set up once in the config and works without interfering with the system settings of each machine. This is especially important for CI/CD pipelines, where it is physically difficult to set up a VPN.

Which Type of Proxy is Suitable for GitHub and npm

Not all proxies work equally well with Git and npm. The choice depends on your task: bypassing blockage, speeding up downloads, or working from a corporate network.

HTTP/HTTPS Proxy

The simplest option. Git and npm natively support HTTP proxies through standard environment variables. Suitable for most tasks: cloning repositories, installing packages, working with the GitHub API. If your proxy provider issues an HTTP address — start with that.

SOCKS5 Proxy

A more flexible protocol, works at the TCP level. Supports any types of traffic, including SSH connections to GitHub (port 22). If you use Git via SSH instead of HTTPS — SOCKS5 is preferable. Git supports SOCKS5 through the socks5:// parameter in the config.

Residential Proxies

Residential proxies use IP addresses of real home users. For GitHub, this is especially relevant if you are working from a country with strict blocking: such IPs are rarely blacklisted and look like regular user traffic. Suitable for situations where datacenter IPs are already blocked at the provider level.

Datacenter Proxies

Datacenter proxies are the optimal choice for most developers. They are faster than residential ones, cheaper, and provide stable connections. If GitHub is just slow, not blocked — a datacenter proxy in the USA or Europe will give the maximum speed increase when cloning and downloading packages.

Setting Up a Proxy for Git: Step-by-Step Instructions

Git supports proxies through the built-in config and through environment variables. We will show both methods — choose the one that is more convenient for your workflow.

Method 1: Through git config (recommended)

This is a permanent setting that applies to all Git operations on the machine. Open the terminal and execute:

# For HTTP/HTTPS proxy
git config --global http.proxy http://username:password@proxy-host:port
git config --global https.proxy http://username:password@proxy-host:port

# For SOCKS5 proxy
git config --global http.proxy socks5://username:password@proxy-host:port
git config --global https.proxy socks5://username:password@proxy-host:port

# Check that the settings have been applied
git config --global --list | grep proxy

Replace username:password@proxy-host:port with your proxy details. If the proxy does not require authentication — remove username:password@.

Method 2: Through Environment Variables

Convenient for temporary use or in scripts. Git automatically picks up the standard variables HTTP_PROXY and HTTPS_PROXY:

# Linux / macOS — add to ~/.bashrc or ~/.zshrc
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"
export NO_PROXY="localhost,127.0.0.1,::1"

# Windows (PowerShell)
$env:HTTP_PROXY="http://username:password@proxy-host:port"
$env:HTTPS_PROXY="http://username:password@proxy-host:port"

# Apply without restarting the terminal (Linux/macOS)
source ~/.bashrc

Setting Up Proxy Only for GitHub

If you want to route only requests to GitHub through the proxy, and not to all repositories, use section settings:

# Proxy only for github.com
git config --global http.https://github.com.proxy http://username:password@proxy-host:port

# Check cloning through the proxy
git clone https://github.com/username/repo.git

Git via SSH through SOCKS5

If you work with GitHub via SSH (not HTTPS), the setup is slightly different. You need to edit the file ~/.ssh/config:

# ~/.ssh/config

Host github.com
    HostName github.com
    User git
    # On Linux/macOS use nc (netcat)
    ProxyCommand nc -X 5 -x proxy-host:port %h %p
    
    # Or through connect-proxy (needs to be installed)
    # ProxyCommand connect -S proxy-host:port %h %p
    
    # On Windows through Git Bash
    # ProxyCommand connect -S proxy-host:port %h %p

After this, the commands git clone [email protected]:user/repo.git and git push will automatically go through the SOCKS5 proxy.

How to Reset Proxy Settings

# Remove the proxy from the global config
git config --global --unset http.proxy
git config --global --unset https.proxy

Setting Up a Proxy for npm, yarn, and pnpm

Each package manager has its own way of setting up a proxy. Let's break down all three — npm, yarn, and pnpm — with specific commands.

npm

npm supports proxies through built-in config settings:

# Set proxy for npm
npm config set proxy http://username:password@proxy-host:port
npm config set https-proxy http://username:password@proxy-host:port

# Check settings
npm config get proxy
npm config get https-proxy

# Test: install a package through the proxy
npm install lodash

# Reset proxy
npm config delete proxy
npm config delete https-proxy

The settings are saved in the file ~/.npmrc. You can edit it directly:

# ~/.npmrc
proxy=http://username:password@proxy-host:port
https-proxy=http://username:password@proxy-host:port
strict-ssl=false

Yarn (v1 Classic)

# Yarn Classic (v1)
yarn config set proxy http://username:password@proxy-host:port
yarn config set https-proxy http://username:password@proxy-host:port

# Check
yarn config get proxy

# Reset
yarn config delete proxy
yarn config delete https-proxy

Yarn Berry (v2+)

# Yarn Berry uses environment variables
# Add to .yarnrc.yml at the root of the project:
httpProxy: "http://username:password@proxy-host:port"
httpsProxy: "http://username:password@proxy-host:port"

# Or through environment variables
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"

pnpm

# pnpm uses the same .npmrc as npm
# Settings are applied automatically if npm is already configured

# Or explicitly through pnpm config
pnpm config set proxy http://username:password@proxy-host:port
pnpm config set https-proxy http://username:password@proxy-host:port

Alternative: npm Registry Mirrors

If the npm registry is slow, but GitHub is accessible — you can switch to a mirror. Popular options: Taobao (for China), Verdaccio (self-hosted). However, mirrors often lag behind in package versions, so a proxy is more reliable:

# Switch the registry to a mirror (only for speeding up, not for blockages)
npm config set registry https://registry.npmmirror.com

# Return to the official registry
npm config set registry https://registry.npmjs.org

Proxy in CI/CD: GitHub Actions, Docker, Jenkins

Setting up a proxy on a local machine is half the battle. The real pain begins when you need to ensure access to GitHub and npm in a CI/CD pipeline that operates in an isolated network. Let's discuss three of the most common scenarios.

GitHub Actions

In GitHub Actions, the proxy is configured through environment variables in the workflow file. Add secrets in the repository settings (Settings → Secrets), then use them in the workflow:

# .github/workflows/build.yml
name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    
    env:
      HTTP_PROXY: ${{ secrets.PROXY_URL }}
      HTTPS_PROXY: ${{ secrets.PROXY_URL }}
      NO_PROXY: "localhost,127.0.0.1"
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Configure npm proxy
        run: |
          npm config set proxy ${{ secrets.PROXY_URL }}
          npm config set https-proxy ${{ secrets.PROXY_URL }}
      
      - name: Install dependencies
        run: npm ci

Docker

In Docker, the proxy is needed at two levels: when building the image (in docker build) and inside the container. These are different settings:

# Pass the proxy when building via --build-arg
docker build \
  --build-arg HTTP_PROXY=http://user:pass@proxy-host:port \
  --build-arg HTTPS_PROXY=http://user:pass@proxy-host:port \
  -t myapp .

# In Dockerfile use ARG for the proxy
# Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN npm ci

# After installing dependencies — reset the proxy (do not store in the image!)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

Global proxy settings for the Docker daemon (for docker pull):

# /etc/docker/daemon.json
{
  "proxies": {
    "http-proxy": "http://user:pass@proxy-host:port",
    "https-proxy": "http://user:pass@proxy-host:port",
    "no-proxy": "localhost,127.0.0.1"
  }
}

# Restart Docker after changes
sudo systemctl restart docker

Jenkins

In Jenkins, the proxy is configured at the agent level through environment variables in the Jenkinsfile or globally in the system settings:

// Jenkinsfile
pipeline {
    agent any
    
    environment {
        HTTP_PROXY  = credentials('proxy-url')
        HTTPS_PROXY = credentials('proxy-url')
        NO_PROXY    = 'localhost,127.0.0.1'
    }
    
    stages {
        stage('Install') {
            steps {
                sh 'npm config set proxy $HTTP_PROXY'
                sh 'npm config set https-proxy $HTTPS_PROXY'
                sh 'npm ci'
            }
        }
        stage('Build') {
            steps {
                sh 'npm run build'
            }
        }
    }
}

Common Errors and How to Fix Them

Even with the correct proxy setup, something may go wrong. We have compiled the most common errors and ways to resolve them.

Error: ECONNREFUSED or Connection refused

The proxy is not responding. Reasons: incorrect address or port, the proxy server is unavailable, credentials have expired.

Solution: Check the availability of the proxy with the command:

curl -v --proxy http://user:pass@proxy-host:port https://github.com

Error: SSL certificate problem / UNABLE_TO_VERIFY_LEAF_SIGNATURE

The proxy intercepts SSL traffic and substitutes its certificate, which Git or npm do not trust.

Solution for Git:

git config --global http.sslVerify false
# Or add the root certificate of the proxy:
git config --global http.sslCAInfo /path/to/proxy-ca.crt

Error: npm ERR! code ENOTFOUND

npm cannot resolve the DNS name of the registry. The proxy is configured, but DNS requests are not going through it.

Solution: Use SOCKS5 instead of HTTP proxy — it tunnels DNS requests:

npm config set proxy socks5://user:pass@proxy-host:port
npm config set https-proxy socks5://user:pass@proxy-host:port

Error: 407 Proxy Authentication Required

The proxy requires authentication, but the credentials were not provided or were provided incorrectly.

# Make sure the username and password in the URL are encoded correctly
# If the password contains special characters (@, :, #) — encode them:
# @ → %40, : → %3A, # → %23

# Example: password "p@ss:word" → "p%40ss%3Aword"
npm config set proxy http://user:p%40ss%3Aword@proxy-host:port

Git clone works, but git push does not

Clone (read) and push (write) may use different protocols. Make sure the proxy is configured for both HTTP and HTTPS. If you are using SSH for push — a separate setup in ~/.ssh/config is needed as described above.

Checklist: Verifying Everything Works

After setting up the proxy, go through this checklist to ensure everything works correctly.

Quick Diagnosis with One Command

If something is not working and it is unclear where the problem lies — run this diagnostic script:

#!/bin/bash
# Proxy diagnostics for GitHub/npm

PROXY="http://user:pass@proxy-host:port"

echo "=== 1. Direct access to GitHub ==="
curl -s -o /dev/null -w "%{http_code}" https://github.com && echo " OK" || echo " FAIL"

echo "=== 2. Access through proxy ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://github.com && echo " OK" || echo " FAIL"

echo "=== 3. Access to npm registry through proxy ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://registry.npmjs.org && echo " OK" || echo " FAIL"

echo "=== 4. Current Git proxy settings ==="
git config --global --list | grep proxy || echo "Git proxy is not set"

echo "=== 5. Current npm proxy settings ==="
npm config get proxy
npm config get https-proxy

Conclusion

Setting up a proxy for GitHub and npm is not a difficult task if you know the right order of actions. Let's summarize:

• To speed up a slow GitHub — datacenter proxies in the USA or Europe are suitable: they are fast, stable, and inexpensive.
• To bypass blockages — residential proxies with IPs of real users provide maximum reliability.
• For Git via HTTPS — configure http.proxy in git config.
• For Git via SSH — use ProxyCommand in ~/.ssh/config.
• For npm/yarn/pnpm — set up proxy through config or environment variables.
• For CI/CD — pass proxy data through secrets, do not hardcode in the code.

Spending 10–15 minutes on setup once gives you stable access to GitHub and npm without depending on the state of the internet connection or blocking policies. The team stops wasting time waiting for slow downloads, CI/CD pipelines run without network errors, and developers in different countries work under the same conditions.

If you are looking for a stable proxy for working with GitHub and npm from countries with restricted access, we recommend considering datacenter proxies — they provide high speed and connection stability, which is critical when cloning repositories and installing dependencies. For regions with strict blockages, residential proxies are better suited — their IPs are practically not subject to restrictions.