Proxies pour GitHub et npm : comment accéder aux dépôts et paquets depuis des pays où GitHub est bloqué ou fonctionne lentement

GitHub est bloqué, fonctionne avec un délai de 10 à 30 secondes ou npm install se fige en cours de route — une situation familière pour les développeurs de Russie, d'Iran, de Chine et d'autres pays. Il existe une solution, et elle est plus simple qu'il n'y paraît : un proxy correctement configuré offre un accès stable aux dépôts, paquets et API GitHub sans VPN et sans complications inutiles.

Pourquoi GitHub et npm bloquent ou ralentissent

Avant de configurer un proxy, il est important de comprendre ce à quoi vous êtes confronté. Les problèmes d'accès à GitHub et npm se divisent en trois types, et chacun nécessite une approche différente.

Blocage total au niveau de l'État

Plusieurs pays — la Chine, l'Iran, la Corée du Nord, et depuis 2022, parfois la Russie — bloquent GitHub au niveau DNS ou par IP. Cela signifie que les requêtes vers github.com ne passent pas du tout ou retournent une erreur de connexion. Le registre npm (registry.npmjs.org) peut fonctionner normalement — ou être également bloqué.

Pare-feux d'entreprise et restrictions réseau

Même sans blocage gouvernemental, les réseaux d'entreprise limitent souvent l'accès aux dépôts externes. C'est une pratique standard dans les banques, les structures gouvernementales et les grandes entreprises : le service informatique bloque les connexions sortantes sur les ports 443 ou bloque des domaines spécifiques. Un développeur dans un tel réseau ne peut pas faire de git clone ou de npm install sans un chemin détourné.

Vitesse lente en raison de la géographie

Techniquement, GitHub est accessible, mais cloner un dépôt de 500 Mo prend 40 minutes, et l'installation des dépendances via npm prend une éternité. C'est un problème de routage : les paquets passent par des nœuds surchargés ou des itinéraires longs. Un serveur proxy situé aux États-Unis ou en Europe réduit le chemin et offre un véritable gain de vitesse de 3 à 10 fois.

Proxy vs VPN : que choisir pour travailler avec le code

De nombreux développeurs se tournent par habitude vers un VPN. C'est compréhensible — un VPN est simple à configurer et fonctionne immédiatement pour l'ensemble du système. Mais pour travailler avec GitHub et npm, un proxy est souvent plus pratique. Examinons la différence.

La conclusion est simple : si votre objectif est de donner à l'équipe un accès à GitHub et npm, le proxy se configure une fois dans la configuration et fonctionne sans intervention dans les paramètres système de chaque machine. Cela est particulièrement important pour les pipelines CI/CD, où il est physiquement difficile de mettre en place un VPN.

Quel type de proxy convient pour GitHub et npm

Tous les proxys ne fonctionnent pas de la même manière avec Git et npm. Le choix dépend de votre objectif : contourner un blocage, accélérer le téléchargement ou travailler depuis un réseau d'entreprise.

Proxy HTTP/HTTPS

La solution la plus simple. Git et npm prennent en charge nativement les proxys HTTP via des variables d'environnement standard. Convient pour la plupart des tâches : clonage de dépôts, installation de paquets, travail avec l'API GitHub. Si votre fournisseur de proxy fournit une adresse HTTP, commencez par cela.

Proxy SOCKS5

Un protocole plus flexible, fonctionnant au niveau TCP. Prend en charge tous les types de trafic, y compris les connexions SSH avec GitHub (port 22). Si vous utilisez Git via SSH plutôt que HTTPS, SOCKS5 est préférable. Git prend en charge SOCKS5 via le paramètre socks5:// dans la configuration.

Proxys résidentiels

Les proxys résidentiels utilisent des adresses IP de véritables utilisateurs domestiques. Pour GitHub, cela est particulièrement pertinent si vous travaillez depuis un pays avec un blocage strict : ces IP sont très rarement mises sur liste noire et ressemblent à un trafic utilisateur normal. Convient pour les situations où les IP des centres de données sont déjà bloquées au niveau du fournisseur.

Proxys de centres de données

Les proxys de centres de données sont le choix optimal pour la plupart des développeurs. Ils sont plus rapides que les résidents, moins chers et offrent une connexion stable. Si GitHub est simplement lent et non bloqué, un proxy de centre de données aux États-Unis ou en Europe offrira le maximum de vitesse lors du clonage et du téléchargement de paquets.

Configuration du proxy pour Git : instructions étape par étape

Git prend en charge les proxys via la configuration intégrée et via des variables d'environnement. Nous montrerons les deux méthodes — choisissez celle qui convient le mieux à votre flux de travail.

Méthode 1 : Via git config (recommandé)

C'est un paramètre permanent qui s'applique à toutes les opérations Git sur la machine. Ouvrez le terminal et exécutez :

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

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

# Vérifiez que les paramètres ont été appliqués
git config --global --list | grep proxy

Remplacez username:password@proxy-host:port par les données de votre proxy. Si le proxy ne nécessite pas d'authentification, supprimez username:password@.

Méthode 2 : Via des variables d'environnement

Pratique pour une utilisation temporaire ou dans des scripts. Git récupère automatiquement les variables standard HTTP_PROXY et HTTPS_PROXY :

# Linux / macOS — ajoutez dans ~/.bashrc ou ~/.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"

# Appliquer sans redémarrer le terminal (Linux/macOS)
source ~/.bashrc

Configuration du proxy uniquement pour GitHub

Si vous souhaitez diriger uniquement les requêtes vers GitHub via le proxy, et non vers tous les dépôts, utilisez la configuration sectionnelle :

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

# Vérification du clonage via le proxy
git clone https://github.com/username/repo.git

Git via SSH avec SOCKS5

Si vous travaillez avec GitHub via SSH (et non HTTPS), la configuration est légèrement différente. Vous devez modifier le fichier ~/.ssh/config :

# ~/.ssh/config

Host github.com
    HostName github.com
    User git
    # Sur Linux/macOS, utilisez nc (netcat)
    ProxyCommand nc -X 5 -x proxy-host:port %h %p
    
    # Ou via connect-proxy (doit être installé)
    # ProxyCommand connect -S proxy-host:port %h %p
    
    # Sur Windows via Git Bash
    # ProxyCommand connect -S proxy-host:port %h %p

Après cela, les commandes git clone [email protected]:user/repo.git et git push passeront automatiquement par le proxy SOCKS5.

Comment réinitialiser les paramètres du proxy

# Supprimer le proxy de la configuration globale
git config --global --unset http.proxy
git config --global --unset https.proxy

Configuration du proxy pour npm, yarn et pnpm

Chaque gestionnaire de paquets a sa propre méthode de configuration du proxy. Examinons les trois — npm, yarn et pnpm — avec des commandes spécifiques.

npm

npm prend en charge le proxy via les paramètres intégrés de la configuration :

# Configurer le proxy pour npm
npm config set proxy http://username:password@proxy-host:port
npm config set https-proxy http://username:password@proxy-host:port

# Vérifier les paramètres
npm config get proxy
npm config get https-proxy

# Test : installation d'un paquet via le proxy
npm install lodash

# Réinitialiser le proxy
npm config delete proxy
npm config delete https-proxy

Les paramètres sont enregistrés dans le fichier ~/.npmrc. Vous pouvez l'éditer directement :

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

# Vérifier
yarn config get proxy

# Réinitialiser
yarn config delete proxy
yarn config delete https-proxy

Yarn Berry (v2+)

# Yarn Berry utilise des variables d'environnement
# Ajoutez dans .yarnrc.yml à la racine du projet :
httpProxy: "http://username:password@proxy-host:port"
httpsProxy: "http://username:password@proxy-host:port"

# Ou via des variables d'environnement
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"

pnpm

# pnpm utilise le même .npmrc que npm
# Les paramètres s'appliquent automatiquement si npm est déjà configuré

# Ou explicitement via pnpm config
pnpm config set proxy http://username:password@proxy-host:port
pnpm config set https-proxy http://username:password@proxy-host:port

Alternative : miroirs du registre npm

Si le registre npm est lent, mais que GitHub est accessible, vous pouvez passer à un miroir. Options populaires : Taobao (pour la Chine), Verdaccio (auto-hébergé). Mais les miroirs sont souvent en retard sur les versions des paquets, donc un proxy est plus fiable :

# Changer le registre vers un miroir (uniquement pour accélérer, pas pour les blocages)
npm config set registry https://registry.npmmirror.com

# Retourner au registre officiel
npm config set registry https://registry.npmjs.org

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

Configurer un proxy sur une machine locale est la moitié du travail. La véritable douleur commence lorsque vous devez garantir l'accès à GitHub et npm dans un pipeline CI/CD qui fonctionne dans un réseau isolé. Examinons trois des scénarios les plus courants.

GitHub Actions

Dans GitHub Actions, le proxy se configure via des variables d'environnement dans le fichier de workflow. Ajoutez des secrets dans les paramètres du dépôt (Settings → Secrets), puis utilisez-les dans le 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

Dans Docker, le proxy est nécessaire à deux niveaux : lors de la construction de l'image (dans docker build) et à l'intérieur du conteneur. Ce sont des paramètres différents :

# Passer le proxy lors de la construction 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 .

# Dans Dockerfile, utiliser ARG pour le proxy
# Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN npm ci

# Après l'installation des dépendances — réinitialiser le proxy (ne pas le conserver dans l'image !)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

Configuration globale du proxy pour le démon Docker (pour 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"
  }
}

# Redémarrer Docker après les modifications
sudo systemctl restart docker

Jenkins

Dans Jenkins, le proxy se configure au niveau de l'agent via des variables d'environnement dans le Jenkinsfile ou globalement dans les paramètres système :

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

Erreurs courantes et comment les corriger

Même avec une configuration correcte du proxy, quelque chose peut mal tourner. Nous avons rassemblé les erreurs les plus courantes et les moyens de les résoudre.

Erreur : ECONNREFUSED ou Connection refused

Le proxy ne répond pas. Raisons : adresse ou port incorrects, serveur proxy inaccessible, expiration des identifiants.

Solution : Vérifiez la disponibilité du proxy avec la commande :

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

Erreur : problème de certificat SSL / UNABLE_TO_VERIFY_LEAF_SIGNATURE

Le proxy intercepte le trafic SSL et insère son propre certificat, que Git ou npm ne reconnaissent pas.

Solution pour Git :

git config --global http.sslVerify false
# Ou ajouter le certificat racine du proxy :
git config --global http.sslCAInfo /path/to/proxy-ca.crt

Erreur : npm ERR! code ENOTFOUND

npm ne peut pas résoudre le nom DNS du registre. Le proxy est configuré, mais les requêtes DNS ne passent pas par lui.

Solution : Utilisez SOCKS5 au lieu d'un proxy HTTP — il tunnelise les requêtes DNS :

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

Erreur : 407 Proxy Authentication Required

Le proxy nécessite une authentification, mais les identifiants ne sont pas fournis ou sont incorrects.

# Assurez-vous que le nom d'utilisateur et le mot de passe dans l'URL sont correctement encodés
# Si le mot de passe contient des caractères spéciaux (@, :, #) — encodez-les :
# @ → %40, : → %3A, # → %23

# Exemple : mot de passe "p@ss:word" → "p%40ss%3Aword"
npm config set proxy http://user:p%40ss%3Aword@proxy-host:port

Git clone fonctionne, mais git push ne fonctionne pas

Clone (lecture) et push (écriture) peuvent utiliser des protocoles différents. Assurez-vous que le proxy est configuré pour HTTP et HTTPS. Si vous utilisez SSH pour push, une configuration distincte dans ~/.ssh/config est nécessaire comme décrit ci-dessus.

Liste de contrôle : vérifions que tout fonctionne

Après avoir configuré le proxy, passez en revue cette liste de contrôle pour vous assurer que tout fonctionne correctement.

Diagnostic rapide avec une seule commande

Si quelque chose ne fonctionne pas et que vous ne savez pas où se trouve le problème, exécutez ce script de diagnostic :

#!/bin/bash
# Diagnostic du proxy pour GitHub/npm

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

echo "=== 1. Accès direct à GitHub ==="
curl -s -o /dev/null -w "%{http_code}" https://github.com && echo " OK" || echo " FAIL"

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

echo "=== 3. Accès au registre npm via le proxy ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://registry.npmjs.org && echo " OK" || echo " FAIL"

echo "=== 4. Paramètres actuels du proxy Git ==="
git config --global --list | grep proxy || echo "Proxy Git non configuré"

echo "=== 5. Paramètres actuels du proxy npm ==="
npm config get proxy
npm config get https-proxy

Conclusion

Configurer un proxy pour GitHub et npm n'est pas une tâche difficile si l'on connaît l'ordre des étapes. Résumons :

• Pour accélérer un GitHub lent — les proxys de centres de données aux États-Unis ou en Europe conviennent : ils sont rapides, stables et peu coûteux.
• Pour contourner les blocages — les proxys résidentiels avec des IP de véritables utilisateurs offrent une fiabilité maximale.
• Pour Git via HTTPS — configurez http.proxy dans git config.
• Pour Git via SSH — utilisez ProxyCommand dans ~/.ssh/config.
• Pour npm/yarn/pnpm — configurez le proxy via la configuration ou les variables d'environnement.
• Pour CI/CD — passez les données du proxy via des secrets, ne les hardcodez pas dans le code.

En consacrant une fois 10 à 15 minutes à la configuration, vous obtenez un accès stable à GitHub et npm sans dépendre de l'état de la connexion Internet ou de la politique de blocage. L'équipe cesse de perdre du temps à attendre des téléchargements lents, les pipelines CI/CD passent sans erreurs réseau, et les développeurs dans différents pays travaillent dans des conditions équivalentes.

Si vous recherchez un proxy stable pour travailler avec GitHub et npm depuis des pays à accès limité, nous vous recommandons de considérer les proxys de centres de données — ils offrent une vitesse élevée et une stabilité de connexion, ce qui est crucial lors du clonage de dépôts et de l'installation de dépendances. Pour les régions avec des blocages stricts, les proxys résidentiels seront plus adaptés — leurs IP ne tombent pratiquement jamais sous les restrictions.