Proxy per GitLab: come configurare l'accesso per il team e i pipeline CI/CD senza interruzioni

```html

GitLab è una piattaforma popolare per l'archiviazione del codice e la gestione dei processi DevOps, utilizzata da migliaia di team in tutto il mondo. Ma cosa fare se l'accesso a GitLab è bloccato a livello di provider, rete aziendale o addirittura di paese? E peggio ancora, quando il pipeline CI/CD fallisce nel mezzo della notte semplicemente perché il runner non riesce a contattare il repository.

In questo articolo vedremo come configurare un proxy per GitLab a livello di client Git, GitLab Runner e server aziendale, in modo che l'intero team lavori in modo stabile da qualsiasi parte del mondo.

Perché è necessario un proxy per GitLab: scenari reali

Prima di configurare un proxy, è importante capire quale problema si sta cercando di risolvere. Le situazioni possono essere diverse e questo influenzerà la scelta del tipo di proxy e il modo in cui si connette.

Scenario 1: GitLab bloccato dal provider o a livello di paese

In alcuni paesi e reti aziendali, l'accesso a gitlab.com è limitato. Un sviluppatore apre il terminale, scrive git pull — e riceve un timeout. In questo caso, il proxy funge da intermediario: il traffico non va direttamente su gitlab.com, ma attraverso un server intermedio in un paese senza restrizioni.

Scenario 2: Team distribuito in diversi paesi

Immagina: parte del team lavora dalla Russia, parte dal Kazakistan, parte dall'Europa. Ognuno ha condizioni di rete diverse, restrizioni diverse. Per garantire che tutti lavorino in modo stabile e alla stessa velocità, le aziende implementano un server proxy aziendale, attraverso il quale tutto il traffico verso GitLab passa attraverso un unico canale.

Scenario 3: CI/CD runner non riesce a contattare le dipendenze esterne

GitLab Runner avvia un pipeline, e durante il passaggio npm install o pip install tutto fallisce — perché il server su cui gira il runner si trova in una rete chiusa senza accesso diretto a Internet. Il proxy consente al runner di ottenere dipendenze esterne senza aprire l'accesso completo a Internet per l'intero server.

Scenario 4: GitLab self-hosted dietro un firewall aziendale

L'azienda mantiene un server GitLab interno nella rete. Gli sviluppatori in remoto devono connettersi ad esso. Invece di utilizzare una VPN per tutto il traffico, è possibile configurare un proxy solo per il traffico di GitLab — è più veloce e più semplice da amministrare.

Scenario 5: Monitoraggio e audit del traffico

Grandi aziende indirizzano tutto il traffico verso i repository attraverso un proxy aziendale per registrare l'attività, controllare chi e cosa viene pushato e bloccare operazioni indesiderate. Questo è un requisito di sicurezza, non un modo per bypassare le restrizioni.

È importante capire prima della configurazione:

Un proxy per GitLab può essere necessario a tre livelli contemporaneamente: sulla macchina dello sviluppatore (client Git), sul server con GitLab Runner (CI/CD) e sul server GitLab stesso (se self-hosted). Ogni livello deve essere configurato separatamente.

Quale tipo di proxy è adatto per GitLab

GitLab funziona sui protocolli HTTPS e SSH. Questo determina immediatamente quali tipi di proxy sono applicabili e quali no. Vediamo le opzioni.

Tipo di proxy	Protocollo	Adatto per GitLab	Quando utilizzare
Proxy HTTP/HTTPS	HTTP, HTTPS	✓ Sì	Git over HTTPS, interfaccia web di GitLab
Proxy SOCKS5	TCP (qualsiasi)	✓ Sì (migliore opzione)	Git over HTTPS e SSH, CI/CD
Proxy SOCKS4	TCP	~ Parzialmente	Solo se SOCKS5 non è disponibile
Proxy trasparente	HTTP	✗ No	Non adatto — non bypassa le restrizioni

Per lavorare con GitLab, la scelta ottimale è SOCKS5. Funziona a livello TCP, quindi proxy sia le connessioni HTTPS (interfaccia web, git clone via HTTPS) che le connessioni SSH (git push/pull via SSH sulla porta 22 o 443).

Proxy residenziali vs proxy da data center per GitLab

Qui tutto dipende dall'obiettivo. Se l'obiettivo è bypassare il blocco GeoIP o ottenere un IP stabile per l'autenticazione, sono adatti i proxy da data center — sono più veloci, più economici e garantiscono una bassa latenza, il che è critico quando si lavora con grandi repository.

Se il tuo IP aziendale è finito nella blacklist di GitLab (può succedere durante la scansione aggressiva o dopo incidenti di sicurezza), allora dovresti considerare i proxy residenziali — i loro indirizzi IP appartengono a veri utenti domestici e vengono raramente bloccati dalle piattaforme.

Configurazione del proxy per il client Git (globale)

Questo è lo scenario più comune: uno sviluppatore sulla propria macchina non riesce a connettersi a GitLab. La configurazione viene effettuata tramite la configurazione di Git stesso — una sola volta, e funziona per tutti i repository.

Opzione A: Proxy HTTPS per Git

Se lavori con GitLab tramite HTTPS (l'indirizzo del repository inizia con https://), esegui nel terminale:

# Imposta il proxy HTTP globalmente
git config --global http.proxy http://IL_TUO_PROXY_IP:PORTA

# Se il proxy richiede autenticazione
git config --global http.proxy http://USERNAME:PASSWORD@IL_TUO_PROXY_IP:PORTA

# Per proxy SOCKS5 (raccomandato)
git config --global http.proxy socks5://IL_TUO_PROXY_IP:PORTA

# Controlla che la configurazione sia stata applicata
git config --global --get http.proxy

Opzione B: Proxy solo per gitlab.com (non influisce su altri repository)

Se non vuoi che il proxy venga applicato a tutte le operazioni Git (ad esempio, GitHub o Bitbucket funzionano normalmente), puoi configurare il proxy solo per un dominio specifico:

# Proxy solo per gitlab.com
git config --global http.https://gitlab.com.proxy socks5://IL_TUO_PROXY_IP:PORTA

# Oppure per il tuo GitLab self-hosted
git config --global http.https://git.yourcompany.com.proxy socks5://IL_TUO_PROXY_IP:PORTA

Opzione C: SSH tramite proxy (per chi lavora tramite SSH)

Se cloni i repository tramite SSH ([email protected]:...), la configurazione del proxy viene effettuata nel file di configurazione SSH, non in Git. Apri il file ~/.ssh/config e aggiungi:

# Per Linux/macOS — tramite nc (netcat)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand nc -X 5 -x IL_TUO_PROXY_IP:PORTA %h %p

# Per Windows — tramite connect.exe (Git for Windows)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand connect -S IL_TUO_PROXY_IP:PORTA %h %p

Dopo la configurazione, verifica la connessione con il comando ssh -T [email protected]. Se tutto è configurato correttamente, vedrai un messaggio di benvenuto da GitLab.

Come disattivare il proxy quando non è più necessario

# Rimuovi il proxy globale
git config --global --unset http.proxy

# Rimuovi il proxy per un dominio specifico
git config --global --unset http.https://gitlab.com.proxy

Proxy per GitLab Runner e pipeline CI/CD

GitLab Runner è un agente che esegue i job da .gitlab-ci.yml. Se il runner si trova in una rete chiusa o su un server con accesso Internet limitato, è necessario configurare un proxy separatamente. Le impostazioni del client Git dello sviluppatore non saranno utili qui — il runner funziona su un'altra macchina.

Metodo 1: Variabili d'ambiente nella configurazione del runner

Apri il file di configurazione di GitLab Runner (di solito /etc/gitlab-runner/config.toml) e aggiungi le variabili d'ambiente nella sezione [runners.env]:

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "IL_TUO_TOKEN"
  executor = "shell"
  environment = [
    "HTTP_PROXY=http://IL_TUO_PROXY_IP:PORTA",
    "HTTPS_PROXY=http://IL_TUO_PROXY_IP:PORTA",
    "NO_PROXY=localhost,127.0.0.1,tuo-dominio-interno.com"
  ]

Dopo aver modificato il config, riavvia il runner: sudo gitlab-runner restart

Metodo 2: Variabili in .gitlab-ci.yml (a livello di pipeline)

Se non sei l'amministratore del runner o vuoi configurare il proxy solo per un progetto specifico, aggiungi le variabili direttamente nel file della pipeline:

variables:
  HTTP_PROXY: "http://IL_TUO_PROXY_IP:PORTA"
  HTTPS_PROXY: "http://IL_TUO_PROXY_IP:PORTA"
  NO_PROXY: "localhost,127.0.0.1,.internal.company.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - npm install   # ora passerà attraverso il proxy
    - npm run build

Metodo 3: Variabili nelle impostazioni del progetto GitLab (senza commit nel repository)

Il modo migliore per dati sensibili (proxy con autenticazione): vai su Settings → CI/CD → Variables del tuo progetto e aggiungi le variabili HTTP_PROXY, HTTPS_PROXY, NO_PROXY come variabili protette (masked). Saranno automaticamente disponibili in tutte le pipeline, ma non saranno visibili nei log.

Proxy per Docker executor

Se il runner utilizza Docker executor, i container per impostazione predefinita non ereditano le impostazioni del proxy dell'host. È necessario aggiungere le variabili nel config.toml nella sezione [runners.docker], oppure creare un file /etc/systemd/system/docker.service.d/proxy.conf sull'host con il runner:

[Service]
Environment="HTTP_PROXY=http://IL_TUO_PROXY_IP:PORTA"
Environment="HTTPS_PROXY=http://IL_TUO_PROXY_IP:PORTA"
Environment="NO_PROXY=localhost,127.0.0.1"

Dopo di che: sudo systemctl daemon-reload && sudo systemctl restart docker

Proxy per server GitLab self-hosted

Se amministri un server GitLab (installato tramite Omnibus o Helm), il proxy è necessario affinché GitLab possa contattare servizi esterni: inviare notifiche, connettersi a sistemi CI esterni, caricare avatar degli utenti, integrarsi con Jira o Slack.

Configurazione in gitlab.rb (installazione Omnibus)

Apri il file /etc/gitlab/gitlab.rb e aggiungi o decommenta le seguenti righe:

# Proxy per GitLab (Omnibus)
gitlab_rails['env'] = {
  "http_proxy" => "http://IL_TUO_PROXY_IP:PORTA",
  "https_proxy" => "http://IL_TUO_PROXY_IP:PORTA",
  "no_proxy" => "localhost,127.0.0.1,IL_TUO_DOMINIO_INTERNO"
}

# Se il proxy richiede autenticazione:
gitlab_rails['env'] = {
  "http_proxy" => "http://USERNAME:PASSWORD@IL_TUO_PROXY_IP:PORTA",
  "https_proxy" => "http://USERNAME:PASSWORD@IL_TUO_PROXY_IP:PORTA",
  "no_proxy" => "localhost,127.0.0.1"
}

Dopo aver modificato il config, applica le impostazioni: sudo gitlab-ctl reconfigure

Configurazione delle connessioni in uscita tramite Admin Area

In GitLab 15.0+ è stata introdotta la possibilità di configurare il proxy direttamente tramite l'interfaccia web: vai su Admin Area → Settings → Network → Outbound requests. Qui puoi specificare un proxy per i webhook in uscita e limitare gli intervalli IP a cui GitLab può accedere. Questo è utile per la sicurezza — previene attacchi SSRF tramite webhook.

Organizzazione dell'accesso per l'intero team tramite proxy

Quando è necessario garantire un accesso stabile a GitLab per un team di 5–50 persone, la configurazione individuale su ogni macchina non è l'approccio migliore. Consideriamo soluzioni più scalabili.

Approccio 1: Server proxy aziendale

Viene implementato un server proxy (ad esempio, Squid o 3proxy) con accesso a Internet. Tutti gli sviluppatori configurano Git per utilizzare questo server. Vantaggi: gestione centralizzata, unico punto di controllo, è possibile registrare il traffico. Svantaggio: il server diventa un unico punto di guasto.

Approccio 2: Mirror (specchio) del repository

GitLab supporta il mirroring dei repository. È possibile configurare un GitLab self-hosted nella rete interna come mirror di gitlab.com. Gli sviluppatori lavorano con il server interno, che si sincronizza con l'esterno tramite proxy. Questo riduce la dipendenza dalla qualità della connessione proxy per ogni sviluppatore.

Approccio 3: Configurazione automatica tramite dotfiles o script di onboarding

Per i team in cui ogni sviluppatore configura l'ambiente da solo, è comodo creare uno script di onboarding che scrive automaticamente le impostazioni Git necessarie. Lo script è conservato in un repository aziendale e viene eseguito durante la configurazione di un nuovo posto di lavoro.

#!/bin/bash
# setup-git-proxy.sh — eseguire durante la configurazione di un nuovo posto di lavoro

PROXY_HOST="proxy.company.com"
PROXY_PORT="3128"

echo "Configurazione del proxy Git per accedere a GitLab..."
git config --global http.https://gitlab.com.proxy "socks5://${PROXY_HOST}:${PROXY_PORT}"
git config --global http.sslVerify true
echo "Fatto! Controlla: git config --global --list | grep proxy"

Checklist per il deployment di team

• Determinare se è necessario un proxy a livello di sviluppatori, runner o server GitLab (o tutti e tre)
• Scegliere il tipo di proxy: SOCKS5 per la massima compatibilità
• Configurare NO_PROXY per tutti i domini e servizi interni
• Controllare il funzionamento delle chiavi SSH tramite proxy (passaggio separato!)
• Documentare le impostazioni nella wiki aziendale
• Creare uno script di onboarding per i nuovi dipendenti
• Configurare il monitoraggio della disponibilità del server proxy

Problemi comuni e loro risoluzione

Anche dopo una corretta configurazione, a volte qualcosa va storto. Ecco i problemi più comuni e i modi per diagnosticarli.

Problema 1: Problema con il certificato SSL: impossibile ottenere il certificato dell'emittente locale

Questo errore si verifica quando il server proxy (soprattutto aziendale) esegue l'ispezione SSL — sostituisce il certificato di GitLab con il proprio. Git non si fida di questo certificato. Soluzione: aggiungere il certificato radice aziendale ai certificati di fiducia.

# Soluzione temporanea (per debug, non per produzione!)
git config --global http.sslVerify false

# Soluzione corretta: aggiungere il certificato aziendale
git config --global http.sslCAInfo /percorso/al/corporate-ca-bundle.crt

Problema 2: Il proxy funziona per HTTPS, ma SSH non funziona

Questa è una situazione classica: hai configurato http.proxy in Git, il cloning HTTPS ha funzionato, ma le operazioni SSH continuano a non andare. La ragione: il traffico SSH non passa attraverso il proxy HTTP. È necessario configurare separatamente ~/.ssh/config come descritto nella sezione sul client Git.

Alternativa: passare a lavorare con GitLab tramite HTTPS invece di SSH. Per fare ciò, modifica l'URL remoto:

# Controlla l'attuale remoto
git remote -v

# Cambia da SSH a HTTPS
git remote set-url origin https://gitlab.com/username/repo.git

Problema 3: Il pipeline CI/CD si blocca durante il cloning del repository

Il runner clona il repository direttamente da GitLab, utilizzando un token. Se il runner si trova dietro un proxy, anche questo cloning deve avvenire tramite proxy. Assicurati che le variabili HTTP_PROXY e HTTPS_PROXY siano impostate in config.toml, e non solo in .gitlab-ci.yml — le variabili del file CI vengono applicate dopo il cloning, non prima.

Problema 4: Il proxy funziona, ma è molto lento

Se push/pull funzionano, ma richiedono 5–10 volte più tempo del solito, il problema potrebbe essere nella larghezza di banda del server proxy o nella sua posizione geografica. Per lavorare con grandi repository (100+ MB) è importante scegliere un proxy con bassa latenza e alta larghezza di banda. I proxy da data center sono preferibili in questo caso rispetto ai residenziali — forniscono un canale più stabile.

Problema 5: L'autenticazione tramite proxy richiede di reinserire la password

Se il proxy richiede autenticazione di base e Git richiede la password ogni volta, configura il credential helper:

# macOS — utilizzare il Keychain
git config --global credential.helper osxkeychain

# Windows — utilizzare il Windows Credential Manager
git config --global credential.helper manager

# Linux — memorizzare nella cache per 1 ora
git config --global credential.helper "cache --timeout=3600"

Conclusione e raccomandazioni

Configurare un proxy per GitLab è un compito che deve essere affrontato a più livelli contemporaneamente. Per uno sviluppatore sulla macchina di lavoro, è sufficiente scrivere un paio di righe nella configurazione di Git o SSH. Per CI/CD, è necessario aggiungere variabili d'ambiente nella configurazione del runner o nelle impostazioni del progetto. E per GitLab self-hosted — aggiornare gitlab.rb e ricostruire la configurazione.

Le regole principali che possono aiutare a evitare la maggior parte dei problemi sono:

• Utilizza SOCKS5 — funziona sia con HTTPS che con SSH
• Configura sempre NO_PROXY per i servizi interni
• Non disattivare la verifica SSL in produzione — aggiungi il certificato aziendale
• Per CI/CD, imposta il proxy in config.toml, e non solo in .gitlab-ci.yml
• Documenta le impostazioni — un nuovo sviluppatore nel team ti ringrazierà

Se stai cercando un proxy affidabile per garantire un accesso stabile a GitLab da qualsiasi parte del mondo, ti consigliamo di considerare i proxy da data center — offrono alta velocità di trasferimento dati e bassa latenza, il che è particolarmente importante quando si lavora con grandi repository e pipeline CI/CD intensive. Per i team che danno importanza alla massima anonimato o al bypass delle restrizioni GeoIP, sono adatti i proxy residenziali con IP di veri utenti domestici.