Proxies para GitHub y npm: cómo acceder a repositorios y paquetes desde países donde GitHub está bloqueado o funciona lentamente

GitHub está bloqueado, funciona con un retraso de 10 a 30 segundos o npm install se queda colgado a mitad de camino: una situación familiar para los desarrolladores de Rusia, Irán, China y varios otros países. Hay una solución, y es más sencilla de lo que parece: un proxy configurado correctamente proporciona acceso estable a los repositorios, paquetes y API de GitHub sin VPN y sin complicaciones innecesarias.

Por qué GitHub y npm bloquean o ralentizan

Antes de configurar un proxy, es importante entender con qué exactamente te has encontrado. Los problemas de acceso a GitHub y npm pueden ser de tres tipos, y cada uno requiere un enfoque diferente.

Bloqueo total a nivel estatal

Varios países — China, Irán, Corea del Norte, y desde 2022, ocasionalmente Rusia — bloquean GitHub a nivel de DNS o por IP. Esto significa que las solicitudes a github.com no pasan en absoluto o devuelven un error de conexión. El registro de npm (registry.npmjs.org) puede funcionar normalmente — o también estar bloqueado.

Firewalls corporativos y restricciones de red

Incluso sin un bloqueo estatal, las redes corporativas a menudo limitan el acceso a repositorios externos. Esta es una práctica estándar en bancos, entidades gubernamentales y grandes empresas: el departamento de TI cierra las conexiones salientes en los puertos 443 o bloquea dominios específicos. Un desarrollador en tal red no puede hacer git clone o npm install sin una ruta alternativa.

Velocidad lenta debido a la geografía

Técnicamente, GitHub es accesible, pero clonar un repositorio de 500 MB toma 40 minutos, y la instalación de dependencias a través de npm — una eternidad. Este es un problema de enrutamiento: los paquetes pasan por nodos congestionados o rutas largas. Un servidor proxy ubicado en EE. UU. o Europa acorta el camino y proporciona un aumento real de velocidad de 3 a 10 veces.

Proxy vs VPN: qué elegir para trabajar con código

Muchos desarrolladores, por costumbre, recurren a VPN. Es comprensible: una VPN es fácil de configurar y funciona de inmediato para todo el sistema. Pero para trabajar con GitHub y npm, un proxy a menudo es más conveniente. Analicemos la diferencia.

La conclusión es sencilla: si tu tarea es dar acceso al equipo a GitHub y npm, el proxy se configura una vez en el archivo de configuración y funciona sin interferir en la configuración del sistema de cada máquina. Esto es especialmente importante para los pipelines de CI/CD, donde es físicamente complicado levantar una VPN.

Qué tipo de proxy es adecuado para GitHub y npm

No todos los proxies funcionan igual de bien con Git y npm. La elección depende de tu tarea: eludir bloqueos, acelerar descargas o trabajar desde una red corporativa.

Proxy HTTP/HTTPS

La opción más sencilla. Git y npm admiten nativamente proxies HTTP a través de variables de entorno estándar. Adecuado para la mayoría de las tareas: clonar repositorios, instalar paquetes, trabajar con la API de GitHub. Si tu proveedor de proxy te da una dirección HTTP, comienza con eso.

Proxy SOCKS5

Un protocolo más flexible que opera a nivel TCP. Admite cualquier tipo de tráfico, incluidas las conexiones SSH con GitHub (puerto 22). Si usas Git a través de SSH en lugar de HTTPS, SOCKS5 es preferible. Git admite SOCKS5 a través del parámetro socks5:// en la configuración.

Proxies residenciales

Los proxies residenciales utilizan direcciones IP de usuarios domésticos reales. Para GitHub, esto es especialmente relevante si trabajas desde un país con bloqueos estrictos: estas IP rara vez caen en listas negras y parecen tráfico de usuario normal. Son adecuados para situaciones donde las IP de centros de datos ya están bloqueadas a nivel de proveedor.

Proxies de centros de datos

Los proxies de centros de datos son la opción óptima para la mayoría de los desarrolladores. Son más rápidos que los residenciales, más baratos y proporcionan una conexión estable. Si GitHub simplemente es lento y no está bloqueado, un proxy de centro de datos en EE. UU. o Europa proporcionará el máximo aumento de velocidad al clonar y descargar paquetes.

Configuración de proxy para Git: instrucciones paso a paso

Git admite proxies a través de la configuración incorporada y a través de variables de entorno. Mostraremos ambos métodos: elige el que sea más conveniente para tu flujo de trabajo.

Método 1: A través de git config (recomendado)

Esta es una configuración permanente que se aplica a todas las operaciones de Git en la máquina. Abre la terminal y ejecuta:

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

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

# Verificar que la configuración se aplicó
git config --global --list | grep proxy

Reemplaza username:password@proxy-host:port con los datos de tu proxy. Si el proxy no requiere autenticación, elimina username:password@.

Método 2: A través de variables de entorno

Conveniente para uso temporal o en scripts. Git automáticamente toma las variables estándar HTTP_PROXY y HTTPS_PROXY:

# Linux / macOS — añade a ~/.bashrc o ~/.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"

# Aplicar sin reiniciar la terminal (Linux/macOS)
source ~/.bashrc

Configuración de proxy solo para GitHub

Si deseas dirigir a través del proxy solo las solicitudes a GitHub y no a todos los repositorios, utiliza la configuración seccional:

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

# Verificar clonación a través del proxy
git clone https://github.com/username/repo.git

Git por SSH a través de SOCKS5

Si trabajas con GitHub a través de SSH (y no HTTPS), la configuración es un poco diferente. Necesitas editar el archivo ~/.ssh/config:

# ~/.ssh/config

Host github.com
    HostName github.com
    User git
    # En Linux/macOS usa nc (netcat)
    ProxyCommand nc -X 5 -x proxy-host:port %h %p
    
    # O a través de connect-proxy (necesita instalación)
    # ProxyCommand connect -S proxy-host:port %h %p
    
    # En Windows a través de Git Bash
    # ProxyCommand connect -S proxy-host:port %h %p

Después de esto, los comandos git clone [email protected]:user/repo.git y git push irán automáticamente a través del proxy SOCKS5.

Cómo restablecer la configuración del proxy

# Eliminar el proxy de la configuración global
git config --global --unset http.proxy
git config --global --unset https.proxy

Configuración de proxy para npm, yarn y pnpm

Cada gestor de paquetes tiene su propia forma de configurar un proxy. Analicemos los tres — npm, yarn y pnpm — con comandos específicos.

npm

npm admite proxies a través de la configuración incorporada:

# Establecer proxy para npm
npm config set proxy http://username:password@proxy-host:port
npm config set https-proxy http://username:password@proxy-host:port

# Verificar configuración
npm config get proxy
npm config get https-proxy

# Prueba: instalación de paquete a través del proxy
npm install lodash

# Restablecer proxy
npm config delete proxy
npm config delete https-proxy

Las configuraciones se guardan en el archivo ~/.npmrc. Puedes editarlo directamente:

# ~/.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

# Verificar
yarn config get proxy

# Restablecer
yarn config delete proxy
yarn config delete https-proxy

Yarn Berry (v2+)

# Yarn Berry utiliza variables de entorno
# Añade en .yarnrc.yml en la raíz del proyecto:
httpProxy: "http://username:password@proxy-host:port"
httpsProxy: "http://username:password@proxy-host:port"

# O a través de variables de entorno
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"

pnpm

# pnpm utiliza el mismo .npmrc que npm
# Las configuraciones se aplican automáticamente si npm ya está configurado

# O explícitamente a través de pnpm config
pnpm config set proxy http://username:password@proxy-host:port
pnpm config set https-proxy http://username:password@proxy-host:port

Alternativa: espejos del registro de npm

Si el registro de npm es lento, pero GitHub es accesible, puedes cambiar a un espejo. Opciones populares: Taobao (para China), Verdaccio (autoalojado). Pero los espejos a menudo se retrasan en las versiones de paquetes, por lo que un proxy es más confiable:

# Cambiar el registro a un espejo (solo para acelerar, no para bloqueos)
npm config set registry https://registry.npmmirror.com

# Volver al registro oficial
npm config set registry https://registry.npmjs.org

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

Configurar un proxy en la máquina local es solo la mitad del trabajo. El verdadero dolor comienza cuando necesitas proporcionar acceso a GitHub y npm en un pipeline de CI/CD que opera en una red aislada. Analicemos tres de los escenarios más comunes.

GitHub Actions

En GitHub Actions, el proxy se configura a través de variables de entorno en el archivo de flujo de trabajo. Agrega secretos en la configuración del repositorio (Configuración → Secretos), luego úsalos en el flujo de trabajo:

# .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

En Docker, el proxy es necesario en dos niveles: al construir la imagen (en docker build) y dentro del contenedor. Estas son configuraciones diferentes:

# Pasar el proxy al construir a través de --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 .

# En Dockerfile usar ARG para el proxy
# Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN npm ci

# Después de instalar dependencias — restablecer el proxy (no almacenar en la imagen!)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

Configuración global del proxy para el demonio de Docker (para 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"
  }
}

# Reiniciar Docker después de los cambios
sudo systemctl restart docker

Jenkins

En Jenkins, el proxy se configura a nivel de agente a través de variables de entorno en el Jenkinsfile o globalmente en la configuración del sistema:

// 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'
            }
        }
    }
}

Errores comunes y cómo solucionarlos

Incluso con una configuración de proxy correcta, algo puede salir mal. Hemos recopilado los errores más comunes y sus soluciones.

Error: ECONNREFUSED o Connection refused

El proxy no responde. Razones: dirección o puerto incorrectos, el servidor proxy no está disponible, las credenciales han caducado.

Solución: Verifica la disponibilidad del proxy con el comando:

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

Error: problema con el certificado SSL / UNABLE_TO_VERIFY_LEAF_SIGNATURE

El proxy intercepta el tráfico SSL y presenta su propio certificado, el cual Git o npm no confían.

Solución para Git:

git config --global http.sslVerify false
# O añadir el certificado raíz del proxy:
git config --global http.sslCAInfo /path/to/proxy-ca.crt

Error: npm ERR! code ENOTFOUND

npm no puede resolver el nombre DNS del registro. El proxy está configurado, pero las solicitudes DNS no pasan a través de él.

Solución: Usa SOCKS5 en lugar de un proxy HTTP; este tuneliza las solicitudes DNS:

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

El proxy requiere autenticación, pero las credenciales no se han proporcionado o se han proporcionado incorrectamente.

# Asegúrate de que el nombre de usuario y la contraseña en la URL estén codificados correctamente
# Si hay caracteres especiales en la contraseña (@, :, #) — codifícalos:
# @ → %40, : → %3A, # → %23

# Ejemplo: contraseña "p@ss:word" → "p%40ss%3Aword"
npm config set proxy http://user:p%40ss%3Aword@proxy-host:port

Git clone funciona, pero git push no

Clone (lectura) y push (escritura) pueden usar diferentes protocolos. Asegúrate de que el proxy esté configurado tanto para HTTP como para HTTPS. Si usas SSH para push, se necesita una configuración separada en ~/.ssh/config como se describió anteriormente.

Lista de verificación: comprobamos que todo funcione

Después de configurar el proxy, revisa esta lista de verificación para asegurarte de que todo funcione correctamente.

Diagnóstico rápido con un solo comando

Si algo no funciona y no está claro dónde está el problema, ejecuta este script de diagnóstico:

#!/bin/bash
# Diagnóstico de proxy para GitHub/npm

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

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

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

echo "=== 3. Acceso al registro de npm a través del proxy ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://registry.npmjs.org && echo " OK" || echo " FAIL"

echo "=== 4. Configuraciones actuales del proxy de Git ==="
git config --global --list | grep proxy || echo "Proxy de Git no configurado"

echo "=== 5. Configuraciones actuales del proxy de npm ==="
npm config get proxy
npm config get https-proxy

Conclusión

Configurar un proxy para GitHub y npm no es una tarea complicada si se conoce el orden correcto de los pasos. Resumamos:

• Para acelerar un GitHub lento — son adecuados los proxies de centros de datos en EE. UU. o Europa: son rápidos, estables y económicos.
• Para eludir bloqueos — los proxies residenciales con IP de usuarios reales garantizan la máxima fiabilidad.
• Para Git a través de HTTPS — configura http.proxy en la configuración de git.
• Para Git a través de SSH — utiliza ProxyCommand en ~/.ssh/config.
• Para npm/yarn/pnpm — configura el proxy a través de la configuración o variables de entorno.
• Para CI/CD — pasa los datos del proxy a través de secretos, no los codifiques en el código.

Al dedicar una vez de 10 a 15 minutos a la configuración, obtienes acceso estable a GitHub y npm sin depender del estado de la conexión a Internet o de la política de bloqueos. El equipo deja de perder tiempo esperando descargas lentas, los pipelines de CI/CD pasan sin errores de red, y los desarrolladores en diferentes países trabajan en condiciones iguales.

Si buscas un proxy estable para trabajar con GitHub y npm desde países con acceso restringido, te recomendamos considerar proxies de centros de datos — proporcionan alta velocidad y estabilidad de conexión, lo cual es crítico al clonar repositorios e instalar dependencias. Para regiones con bloqueos estrictos, son más adecuados proxies residenciales — sus IP rara vez caen bajo restricciones.