Configuração de proxy no Git

A configuração de proxy no Git envolve ajustar as opções http.proxy e https.proxy do Git, ou usar variáveis de ambiente como HTTP_PROXY e HTTPS_PROXY, ou ainda usar ProxyCommand nas configurações de SSH para operações Git via SSH, de modo a rotear o tráfego por um servidor intermediário.

Entendendo os requisitos de proxy no Git

Firewalls corporativos, políticas de segurança de rede ou acesso restrito à internet frequentemente obrigam a rotear o tráfego do Git por um servidor proxy. Isso vale para operações como git clone, git fetch, git pull e git push. O método de configuração depende do protocolo da URL do Git: https:// (ou http://) usa proxies HTTP/HTTPS, enquanto ssh:// (ou git@) usa métodos de proxy específicos de SSH.

Configuração de proxy HTTP/HTTPS no Git

Para repositórios Git acessados por URLs https:// ou http://, o Git utiliza as configurações de proxy HTTP/HTTPS.

Método de configuração do Git (git config)

Este é o método recomendado para configurar proxies HTTP/HTTPS no Git. As configurações podem ser globais (para todos os repositórios) ou específicas de um único repositório.

Configuração global

Para configurar um proxy globalmente, para todos os repositórios Git do sistema:

# For HTTP proxy (e.g., for https://github.com URLs through an http proxy)
git config --global http.proxy http://proxy.example.com:8080

# For HTTPS proxy (e.g., for https://github.com URLs through an https proxy)
# Note: Often an HTTPS proxy is configured similarly to an HTTP proxy,
# but traffic is explicitly tunneled.
git config --global https.proxy http://proxy.example.com:8080

Se o proxy exigir autenticação:

git config --global http.proxy http://username:[email protected]:8080
git config --global https.proxy http://username:[email protected]:8080

Por segurança, em vez de embutir a senha diretamente na URL, o Git pode solicitar as credenciais ou obtê-las de um credential helper. Omitir a senha faz o Git pedi-la.

Configuração por repositório

Para configurar um proxy em um repositório específico, vá até o diretório raiz do repositório e omita a flag --global:

cd /path/to/my/repo
git config http.proxy http://proxy.example.com:8080
git config https.proxy http://proxy.example.com:8080

Essas configurações ficam armazenadas no arquivo .git/config daquele repositório.

Desativando o proxy para hosts específicos

Para ignorar o proxy em determinados domínios (por exemplo, servidores Git internos), use http.noProxy:

git config --global http.noProxy "localhost,127.0.0.1,*.internal.com"

Vários hosts podem ser separados por vírgula.

Verificação de certificado SSL

Em ambientes corporativos com proxies transparentes ou interceptadores (proxies MITM), a verificação de certificado SSL do Git pode falhar, porque o proxy apresenta o próprio certificado no lugar do certificado do servidor de origem.

Para resolver isso, configure o Git para confiar no certificado da CA raiz corporativa:

git config --global http.sslCAInfo /path/to/corporate/ca-cert.pem

Alternativamente, e não recomendado em ambientes de produção por causa dos riscos de segurança, a verificação SSL pode ser desativada:

git config --global http.sslVerify false

Isso ignora a validação de certificados, tornando as conexões vulneráveis a ataques man-in-the-middle reais. Use apenas para depuração temporária ou em ambientes controlados e isolados.

Variáveis de ambiente

Ferramentas de linha de comando, incluindo o curl (que o Git costuma usar para transferências HTTP/HTTPS), normalmente respeitam as variáveis de ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY. Essas variáveis fornecem uma configuração de proxy válida para todo o sistema ou para a sessão, que os aplicativos podem herdar.

# For HTTP proxy
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080" # Often the same for HTTPS traffic tunneling

# For SOCKS proxy
export ALL_PROXY="socks5://proxy.example.com:1080"

# Exclude specific hosts from proxy
export NO_PROXY="localhost,127.0.0.1,*.internal.com"

Observe que as configurações http.proxy e https.proxy do Git têm precedência sobre essas variáveis de ambiente nas próprias operações HTTP/HTTPS do Git. As variáveis de ambiente são úteis quando o git config não está explicitamente definido, ou para outras ferramentas que interagem com o Git.

Comparação: git config vs. variáveis de ambiente

Configuração de proxy Git via SSH

Para repositórios Git acessados por URLs ssh:// ou git@, o proxy é configurado no cliente SSH, especificamente com a diretiva ProxyCommand em ~/.ssh/config. As configurações padrão de proxy HTTP/HTTPS (por exemplo, http.proxy) não afetam conexões SSH.

Usando ~/.ssh/config com ProxyCommand

O ProxyCommand diz ao SSH para estabelecer a conexão com o host de destino (%h) e a porta (%p) roteando-a primeiro por um comando externo, normalmente um cliente de proxy.

Pré-requisitos

• netcat (nc): para tunelamento TCP básico e proxies SOCKS.
• corkscrew ou connect-proxy: para tunelar SSH por proxies HTTP/HTTPS que exigem autenticação.

Tunelamento por proxy HTTP/HTTPS

Se o seu proxy for HTTP/HTTPS, você pode usar corkscrew ou connect-proxy.

1. Instale corkscrew ou connect-proxy (se ainda não estiverem presentes).

   • No Debian/Ubuntu: sudo apt-get install corkscrew
   • No macOS (com Homebrew): brew install corkscrew
   • O connect-proxy costuma vir junto com o openssh ou estar disponível separadamente.

2. Edite ~/.ssh/config:
   Crie ou altere ~/.ssh/config com o seguinte:

   ```ssh
   Host github.com
   ProxyCommand corkscrew proxy.example.com 8080 %h %p
   # If proxy requires authentication:
   # ProxyCommand corkscrew proxy.example.com 8080 %h %p /path/to/proxy_auth_file

   Host gitlab.com
   ProxyCommand corkscrew proxy.example.com 8080 %h %p

   Or for all hosts

   Host *
   ProxyCommand corkscrew proxy.example.com 8080 %h %p
   `` Substituaproxy.example.come8080pelo endereço e pela porta do seu proxy. O arquivo/path/to/proxy_auth_filedeve conterusername:passwordem uma única linha. Garanta permissões restritivas para esse arquivo (por exemplo,chmod 600`).

Tunelamento por proxy SOCKS

Se o seu proxy for SOCKS, use o netcat (nc) com a opção -X:

1. Confirme que o netcat está instalado. Ele normalmente já vem pré-instalado na maioria dos sistemas Unix-like.

2. Edite ~/.ssh/config:

   ```ssh
   Host github.com
   ProxyCommand nc -X 5 -x proxy.example.com:1080 %h %p

   Host gitlab.com
   ProxyCommand nc -X 5 -x proxy.example.com:1080 %h %p

   Or for all hosts

   Host *
   ProxyCommand nc -X 5 -x proxy.example.com:1080 %h %p
   `` Substituaproxy.example.come1080pelo endereço e pela porta do seu proxy SOCKS. *-X 5: especifica SOCKS versão 5. Use-X 4para SOCKS versão 4. *-x`: especifica o endereço e a porta do proxy.

Autenticação em proxy SOCKS

Algumas versões do netcat (o nc do OpenBSD, muitas vezes padrão no Linux) suportam autenticação em proxy SOCKS. Por exemplo:

Host *
    ProxyCommand nc -X 5 -x user:[email protected]:1080 %h %p

Consulte a man page da sua versão do netcat para a sintaxe e os recursos exatos de autenticação.

Verificando a configuração do proxy

Depois de configurar o proxy, verifique se as operações do Git estão sendo roteadas corretamente.

Para operações Git HTTP/HTTPS

Confira sua configuração do Git:

git config --global --get http.proxy
git config --global --get https.proxy
git config --global --get http.noProxy

Execute um git clone ou git fetch em um repositório HTTPS:

git clone https://github.com/git/git.git

Se o proxy estiver funcionando, a conexão deve ser bem-sucedida. Ferramentas de monitoramento de rede podem confirmar o roteamento do tráfego.

Para operações Git via SSH

Teste sua conexão SSH em modo verboso:

ssh -vT [email protected]

Procure na saída a indicação de execução do ProxyCommand. Por exemplo:

debug1: Executing proxy command: exec corkscrew proxy.example.com 8080 github.com 22

Em seguida, tente uma operação Git:

git clone [email protected]:git/git.git

Solução de problemas comuns

• Endereço ou porta de proxy incorretos: confira o IP ou hostname do servidor proxy e a porta indicada.
• Falha de autenticação: verifique usuário e senha do proxy. Para git config, confirme se as credenciais estão corretas ou se há um credential helper configurado. Para ProxyCommand, confirme se o arquivo de autenticação ou as credenciais embutidas estão corretos.
• Problemas de certificado SSL (https://): se aparecerem erros do tipo SSL certificate problem: self signed certificate in certificate chain, seu proxy corporativo pode estar fazendo inspeção SSL. Configure http.sslCAInfo com o certificado da CA raiz corporativa ou, como último recurso, defina temporariamente http.sslVerify false para depuração (não recomendado em produção).
• Bloqueios de firewall: garanta que seu firewall local (se houver) e o firewall corporativo permitam conexões de saída para o servidor proxy na porta especificada. O próprio servidor proxy também precisa permitir conexões com os serviços de hospedagem Git.
• Auxiliar do ProxyCommand não encontrado (ssh://): se o ProxyCommand falhar com "command not found", confirme que netcat, corkscrew ou connect-proxy estão instalados e que o caminho do executável está na variável de ambiente PATH do sistema. Se necessário, informe o caminho completo do executável (por exemplo, ProxyCommand /usr/bin/corkscrew ...).
• Proxy ignorado: se o http.noProxy do git config for amplo demais, ou se as variáveis de ambiente estiverem definidas incorretamente, o Git pode tentar uma conexão direta. Verifique as configurações de noProxy.
• Timeout do proxy: operações longas podem estourar o tempo limite se o proxy tiver timeouts agressivos. Isso costuma ser uma questão de configuração do lado do servidor.