Configurar proxy no Git: como usar o Git atrás de um proxy

Publicado:

17 min de leitura

Acar Diveroli
Autor: Acar Diveroli
Diagrama: linha de um cliente Git cruza uma elipse pontilhada http.proxy e segue azul ao remoto; um arco NO_PROXY vai direto

Num notebook de trabalho novo, o git clone fica parado por vinte segundos e depois desiste com Failed to connect to … :443. O navegador da mesma máquina abre a página do repositório sem dificuldade, porque o navegador conhece o proxy da empresa e o Git não. O mesmo acontece num servidor de build que só pode sair por um único gateway, ou quando um servidor Git próprio aceita conexões de um só endereço liberado na sua lista de permissões.

Este guia mostra o http.proxy e seus escopos, as regras por host, as variáveis de ambiente que o Git lê e qual delas vence, SOCKS5, credenciais com caracteres especiais, remotos SSH, a remoção das configurações e os textos exatos dos erros. Cada comando foi executado com o Git 2.56 no Windows 11 contra pequenos proxies de teste em 127.0.0.1, com um arquivo de configuração descartável, para que nenhuma configuração real do Git fosse alterada.

Quando o Git precisa de um proxy?

O Git precisa de um proxy sempre que a rede não o deixa alcançar o remoto diretamente, ou quando o remoto só aceita um endereço conhecido: uma rede corporativa com proxy de saída, um runner de CI numa sub-rede fechada, um servidor Git próprio que libera um único IP na lista de permissões. É comum o navegador funcionar enquanto o Git falha, porque o navegador segue o proxy do sistema e o Git lê apenas a própria configuração e algumas variáveis de ambiente.

O Git tem três maneiras de conversar com um remoto, e cada uma busca o proxy num lugar diferente. Antes de mudar qualquer coisa, veja a URL do remoto com git remote -v.

Como o Git envia o tráfego por um proxy?

O Git entrega os remotos HTTP e HTTPS à libcurl, a biblioteca por trás do comando curl, então o tráfego HTTPS segue o fluxo normal de um proxy:

  1. O Git lê o endereço do proxy em http.<url>.proxy, depois em http.proxy, depois nas variáveis de ambiente, e confere o host contra o NO_PROXY.
  2. Ele abre uma conexão TCP com o proxy e, para um remoto https://, envia CONNECT git.example.com:443. Nosso proxy de teste registrou exatamente essa linha, com o user agent git/2.56.0.windows.4.
  3. Se o proxy responde 407, o Git repete o CONNECT com um cabeçalho Proxy-Authorization montado a partir das credenciais da URL do proxy.
  4. Depois de 200 Connection established, o TLS acontece dentro do túnel. O proxy vê o nome do host e a porta, não o conteúdo do repositório.
  5. O servidor Git vê o IP de saída do proxy, e é isso que uma lista de permissões verifica.
URL do remotoTransporteConfiguração de proxy
https://git.example.com/team/app.gitHTTPS pela libcurlhttp.proxy, variáveis de ambiente
http://git.example.com/team/app.gitHTTP pela libcurlhttp.proxy, http_proxy
git@git.example.com:team/app.gitSSHProxyCommand, ProxyJump
ssh://git@git.example.com/team/app.gitSSHProxyCommand, ProxyJump
git://git.example.com/app.gitProtocolo Gitcore.gitProxy

Como configurar um proxy no Git?

Defina o http.proxy com git config. O valor é uma URL no formato [protocol://][user[:password]@]proxyhost[:port], como a documentação do git-config estabelece:

bash
git config --global http.proxy http://user:pass@pr.proxynet.io:8000
git config --global --get http.proxy

Na nossa máquina de teste, o segundo comando devolveu a mesma URL, e o arquivo de configuração ganhou uma seção [http] com uma linha proxy =.

Não existe uma chave https.proxy separada no Git. O http.proxy cobre remotos HTTP e HTTPS, e o http:// no início do valor descreve como o Git fala com o proxy, não com o remoto. Um proxy que espera TLS por conta própria recebe um valor https://, e o http.proxySSLCAInfo aponta o pacote de certificados usado para verificá-lo.

Escopo global, de sistema ou de repositório

A opção define qual arquivo recebe a linha:

  • --global grava em ~/.gitconfig e vale para todos os repositórios da sua conta de usuário.
  • --system grava no arquivo etc/gitconfig da instalação e vale para todos os usuários da máquina.
  • --local, o padrão quando nenhuma opção é passada, grava em .git/config e vale só para o repositório atual.

Quando a mesma chave aparece em vários arquivos, o valor do repositório vence o global, que vence o do sistema. Um colega que "já configurou o proxy" mas continua sem conseguir clonar muitas vezes rodou o comando dentro de um único repositório, sem --global.

Só para um comando

Para testar um proxy sem salvar nada, passe-o com -c antes do subcomando:

bash
git -c http.proxy=http://user:pass@pr.proxynet.io:8000 ls-remote https://git.example.com/team/app.git

O git ls-remote só lista os branches de um remoto, então é um teste de conectividade rápido e inofensivo.

Como usar um proxy só para um host?

Coloque o endereço do remoto dentro da chave: http.<url>.proxy. O Git compara cada URL de requisição com essas chaves e usa a correspondência mais específica, de modo que a mesma máquina alcança um host externo pelo proxy e um interno diretamente:

bash
# proxy só para este host
git config --global http.https://git.example.com.proxy http://user:pass@pr.proxynet.io:8000

# proxy global, mas nunca para o servidor interno
git config --global http.proxy http://user:pass@pr.proxynet.io:8000
git config --global http.https://git.internal.example.proxy ""

Um valor vazio desliga o proxy para aquele endereço. No nosso teste, o host isento foi contatado diretamente mesmo com o http.proxy e a variável https_proxy apontando para um proxy, e o git config --get-urlmatch http.proxy <url> devolveu uma linha vazia para ele e o proxy para qualquer outro host.

A correspondência segue uma ordem fixa: esquema, host, porta, caminho e nome de usuário. Um * no host vale para um único nível de subdomínio (https://*.example.com cobre git.example.com, mas não a.b.example.com), e um caminho mais longo vence um mais curto. Um remoto também pode ter o próprio remote.origin.proxy; uma string vazia ali desativa o proxy para aquele remoto.

O Git usa HTTP_PROXY, HTTPS_PROXY e NO_PROXY?

Sim. Quando o http.proxy não está definido, o Git pega o proxy das mesmas variáveis de ambiente que o curl: https_proxy para remotos HTTPS, http_proxy para remotos HTTP e all_proxy como alternativa para os dois. O NO_PROXY guarda uma lista de hosts separados por vírgula que devem ser acessados sem proxy.

Apontamos as variáveis e a configuração para dois proxies de teste diferentes e observamos qual recebia o CONNECT:

CenárioO que aconteceu
https_proxy e http.proxy definidosUsou o http.proxy
Só HTTPS_PROXY (maiúsculas)Usou o proxy
Só HTTP_PROXY, remoto HTTPSConexão direta
Só all_proxyUsou o proxy
http.proxy mais NO_PROXY=.internal.testConexão direta

Duas linhas surpreendem muita gente. O HTTP_PROXY sozinho não faz nada para um remoto HTTPS, então o clone sai direto. E o NO_PROXY também isenta hosts de um proxy definido na configuração do Git: útil para servidores internos, confuso quando um valor esquecido fica no perfil do seu shell. As entradas valem para o próprio host ou para qualquer host sob aquele domínio, então internal.test também cobre git.internal.test.

No Linux e no macOS, maiúsculas e minúsculas fazem diferença. A documentação do curl sobre proxies explica que o http_proxy só é lido em minúsculas, porque um servidor web que roda um script CGI transforma um cabeçalho Proxy: recebido numa variável HTTP_PROXY em maiúsculas; as demais variáveis de proxy funcionam das duas formas. Na nossa máquina Windows a forma em maiúsculas também funcionou, já que o Windows não diferencia maiúsculas de minúsculas nos nomes de variáveis.

Como usar um proxy SOCKS5 com o Git?

Escreva um esquema SOCKS na mesma chave http.proxy. A libcurl aceita socks4://, socks4a://, socks5:// e socks5h://, e a diferença entre os dois últimos é onde o nome do host é resolvido:

bash
git config --global http.proxy socks5h://user:pass@pr.proxynet.io:1080

Com socks5://, o Git consulta o endereço IP do remoto na sua máquina e pede ao proxy que se conecte a esse número. Com socks5h://, ele envia o nome do host e o proxy faz a resolução. Nosso servidor SOCKS de teste deixou a diferença visível: o mesmo ls-remote chegou como CONNECT IPv4 104.20.23.154 port 443 com socks5:// e como CONNECT DOMAIN example.com port 443 com socks5h://.

Use socks5h:// quando a sua rede não consegue resolver nomes externos ou quando as consultas DNS não devem sair da sua máquina. A referência da libcurl sobre proxies também observa que uma URL de proxy sem porta usa 1080 por padrão, então escreva sempre a porta do seu endpoint.

Um endpoint de Proxies SOCKS5 entra na mesma chave; o funcionamento do protocolo passo a passo está em [Proxy SOCKS5:

o que é e como funciona](/pt-br/blog/socks5-proxy-101).

Como passar as credenciais do proxy com segurança?

Coloque o nome de usuário e a senha na URL do proxy e aplique codificação percentual a todo caractere que tenha significado numa URL. Os mais comuns são @ como %40, : como %3A, # como %23, / como %2F e o espaço como %20:

bash
# senha p@ss:w#rd
git config --global http.proxy "http://user:p%40ss%3Aw%23rd@pr.proxynet.io:8000"

No nosso proxy de teste, a forma codificada chegou como user:p@ss:w#rd, exatamente como pretendido. A forma crua, http://user:p@ss:w#rd@…, nunca chegou ao proxy: o Git parou com Invalid proxy URL … only SOCKS proxies support paths, porque o primeiro @ e o # quebraram a URL.

Uma senha no ~/.gitconfig fica gravada em texto puro, então há duas saídas mais limpas. Deixe a senha de fora (http://user@pr.proxynet.io:8000) e o Git vai pedi-la pelo seu sistema de credenciais, o mesmo que guarda os logins dos repositórios; com os prompts desativados, nossa execução parou com could not read Password … terminal prompts disabled. Ou dispense as credenciais de vez: quando o IP da máquina está na whitelist do proxy, a URL é apenas http://pr.proxynet.io:8000. A Proxynet aceita até 10 IPs na whitelist, o que combina com um servidor de build de endereço fixo.

anyauth ou basic?

O http.proxyAuthMethod define como o Git faz login. O padrão, anyauth, primeiro envia o CONNECT sem credenciais e espera um 407 que informe os métodos aceitos; o basic envia o usuário e a senha já na primeira requisição. Nossos proxies de teste mostraram quando isso importa:

Comportamento do proxyanyauth (padrão)basic
407 com desafio, conexão mantidaFunciona, duas requisiçõesFunciona, uma requisição
407 com desafio, depois fechaProxy CONNECT abortedFunciona
407 sem Proxy-Authenticateresponse 407Funciona

Se aparecer Proxy CONNECT aborted com a senha correta, tente primeiro git config --global http.proxyAuthMethod basic. O Basic envia a senha codificada em base64, não criptografada, então use-o apenas em redes confiáveis.

O http.proxy funciona com remotos SSH?

Não. Um remoto como git@git.example.com:team/app.git roda sobre SSH, e o Git inicia o programa ssh para ele; o http.proxy e as variáveis de proxy nunca são consultados. Com o http.proxy definido, nosso teste SSH ignorou o proxy por completo e falhou com ssh: Could not resolve hostname. Se o SSH em si é novidade para você, O que é SSH explica as chaves e a verificação do host.

O SSH tem duas opções de proxy próprias, descritas no manual do ssh_config:

  • ProxyCommand roda um programa auxiliar que abre a conexão por um proxy; %h e %p representam o host e a porta de destino. O nc do OpenBSD, presente em muitos sistemas Linux e macOS, faz isso: ProxyCommand nc -X connect -x pr.proxynet.io:8000 %h %p para um proxy HTTP, -X 5 para SOCKS5. O manual dele diz que a autenticação no proxy só funciona com proxies HTTP CONNECT, então a whitelist de IP é o caminho mais simples aqui.
  • ProxyJump encaminha a conexão por outro servidor SSH (um host de salto, ou bastion) em vez de um proxy web: ProxyJump user@jump.example.com.

Coloque a linha sob um bloco Host no ~/.ssh/config para que só o servidor Git a use:

text
Host git.example.com
    ProxyCommand nc -X 5 -x pr.proxynet.io:1080 %h %p

Para um único repositório ou um único comando, passe a opção pelo core.sshCommand ou pela variável GIT_SSH_COMMAND. Na nossa máquina de teste usamos o connect, um pequeno programa auxiliar presente no ambiente Git daquela máquina, e os proxies registraram CONNECT DOMAIN git.internal.test port 22 (SOCKS5) e CONNECT git.internal.test:22 (HTTP). Alguns proxies HTTP só permitem CONNECT para a porta 443, então confirme que a porta 22 está liberada ou mude o remoto para HTTPS. O antigo protocolo git:// tem a sua própria chave, core.gitProxy, raramente necessária hoje.

Como verificar e remover as configurações de proxy do Git?

Leia o valor primeiro, incluindo de onde ele vem. Estes comandos respondem à maioria das dúvidas do tipo "por que o Git ainda usa o proxy antigo?":

bash
git config --get http.proxy                     # valor que o Git usa neste repositório
git config --show-origin --get-all http.proxy   # cada valor e o arquivo onde ele está
git config --get-urlmatch http.proxy https://git.example.com/team/app.git
env | grep -i proxy                             # variáveis (PowerShell: Get-ChildItem env:*proxy*)

Remova um valor com --unset no mesmo escopo em que você o definiu:

bash
git config --global --unset http.proxy
git config --global --unset http.https://git.example.com.proxy
git config --global --unset-all http.proxy      # se a chave aparecer mais de uma vez

Uma chave adicionada duas vezes faz o --unset simples recusar com warning: http.proxy has multiple values; o --unset-all apaga as duas. Remova as variáveis com unset https_proxy no bash ou Remove-Item Env:https_proxy no PowerShell, e apague a linha do perfil que as definia.

Para acompanhar a conversa com o proxy, rode um comando com GIT_TRACE_CURL=1. Por padrão, o Git oculta o cabeçalho Proxy-Authorization nesse rastreamento, mas trate a saída como sensível mesmo assim.

Qual proxy combina com o tráfego do Git?

Um proxy com endereço de saída fixo é o que melhor combina com o Git, porque o motivo habitual para passar o Git por um proxy de terceiros é uma lista de permissões no servidor Git, num espelho de pacotes ou na rede de um parceiro. Os Proxies de datacenter oferecem um endereço IPv4 dedicado que continua o mesmo entre clones e reinicializações, então a entrada na lista de permissões é escrita uma única vez; endereços rotativos trabalham contra esse objetivo.

Produtos vendidos por IP, como os proxies de datacenter, vêm por padrão com uma restrição de sites de destino, e o acesso a todos os sites é um adicional pago, então confirme que o seu host Git está acessível pelos seus IPs antes de ligá-lo à CI. Numa rede corporativa, o proxy mantido pela sua equipe de TI continua sendo a resposta certa.

Onde você encontra as configurações de proxy do Git

Notebooks corporativos são o caso clássico: toda conexão de saída passa por um proxy que inspeciona o tráfego, e o Git é informado uma vez na configuração global. Em seguida vêm os runners de CI, normalmente por variáveis de ambiente na definição do job, para que o Git, o gerenciador de pacotes e o curl compartilhem uma única configuração. Servidores Git próprios e espelhos de artefatos que aceitam uma lista curta de endereços de origem precisam de um IP de saída estável, e equipes que trabalham por um bastion encontram o lado SSH, em que o ProxyJump substitui qualquer proxy web.

Erros comuns de proxy no Git e como corrigi-los

Os textos abaixo são o que o Git 2.56 com a libcurl 8.23 exibiu na nossa máquina de teste depois de fatal: unable to access '<url>':. Versões mais antigas do curl escrevem alguns deles de forma um pouco diferente.

  • Failed to connect to git.example.com:443 over proxy 127.0.0.1 after 0 ms: Could not connect to server. O próprio proxy está inacessível: porta errada, um firewall, ou o proxy caiu.
  • A mesma mensagem sem over proxy. O Git não usou proxy nenhum. Verifique --show-origin --get-all http.proxy, o esquema da URL e o NO_PROXY.
  • Could not resolve proxy: proxy.invalid. O nome do host do proxy não resolve.
  • Could not resolve host: git.example.com. O Git saiu direto, ou um proxy socks5:// precisa de uma consulta DNS que a sua rede não consegue fazer. Defina o proxy ou use socks5h://.
  • CONNECT tunnel failed, response 407. O proxy recusou as credenciais ou não recebeu nenhuma. Verifique o nome de usuário, a codificação da senha e a whitelist de IP; Como corrigir HTTP 407 Proxy Authentication Required percorre todas as causas.
  • Proxy CONNECT aborted. Muitas vezes é o handshake anyauth falhando num proxy que fecha a conexão depois do seu 407. Defina http.proxyAuthMethod como basic.
  • Invalid proxy URL … only SOCKS proxies support paths. Há um @, # ou / sem codificação na senha.
  • cannot complete SOCKS5 connection to … (2). O proxy SOCKS recusou o destino; o número é o código de resposta do SOCKS (2 significa "não permitido pelo conjunto de regras").
  • SSL certificate problem: unable to get local issuer certificate. Um proxy que inspeciona TLS assina o tráfego de novo com um certificado da empresa em que o Git não confia. Aponte o http.sslCAInfo para um pacote com o certificado raiz da empresa ou, no Git for Windows, defina http.sslBackend como schannel para usar o repositório de certificados do Windows.
  • Uma espera longa que termina em timeout. Um firewall descarta os pacotes, geralmente porque o Git sai direto numa rede que só permite passar pelo proxy.

O http.sslVerify false e o GIT_SSL_NO_VERIFY escondem o erro de certificado desligando a verificação que protege você de um ataque man-in-the-middle. Use-os no máximo para um único comando de diagnóstico, nunca como solução.

Guia de decisão

NecessidadeRecomendação
Todos os remotos HTTPS por um proxygit config --global http.proxy
Só um host externohttp.<url>.proxy
Servidor interno precisa ir diretohttp.<url>.proxy vazio ou NO_PROXY
Job de CI com várias ferramentasVariáveis https_proxy e NO_PROXY
SOCKS5 com DNS no proxysocks5h:// no http.proxy
Nenhuma senha em arquivos de configuraçãoWhitelist de IP ou só o nome de usuário
Proxy CONNECT abortedhttp.proxyAuthMethod basic
Remotos git@ ou ssh://ProxyCommand ou ProxyJump
Inspeção TLS da empresahttp.sslCAInfo ou schannel

Perguntas frequentes

Como configuro um proxy no Git?

Execute git config --global http.proxy http://host:port, com user:pass@ antes do host se o proxy exigir login. A configuração vale para todos os remotos HTTP e HTTPS da sua conta; confira com git config --global --get http.proxy.

Como removo o proxy do Git?

Execute git config --global --unset http.proxy, com a mesma opção de escopo usada para defini-lo. Se o Git continuar usando um proxy, procure um valor de repositório com git config --show-origin --get-all http.proxy e verifique se há https_proxy ou all_proxy no seu ambiente.

Existe uma configuração https.proxy no git config?

Não. A documentação do Git define apenas http.proxy, e essa única chave cobre remotos HTTP e HTTPS. Para um único host HTTPS, use http.https://host.proxy.

Como uso um proxy SOCKS5 com o Git?

Defina o http.proxy como socks5h://user:pass@host:port; o h faz o proxy resolver os nomes de host. Isso cobre os remotos HTTPS, enquanto os remotos SSH precisam de ProxyCommand com um programa auxiliar compatível com SOCKS, como o nc -X 5.

O Git usa as configurações de proxy do Windows?

Não conte com isso. A documentação do Git cita como fontes de proxy apenas as próprias chaves http.proxy e a família de variáveis https_proxy. Defina o http.proxy de forma explícita e teste com git ls-remote.

Por que o git clone por SSH ignora o meu proxy?

Porque o http.proxy só afeta remotos HTTP e HTTPS. Remotos SSH precisam de uma linha ProxyCommand ou ProxyJump no ~/.ssh/config ou no core.sshCommand; como alternativa, clone a URL HTTPS do mesmo repositório.

Em resumo

O Git busca o proxy HTTPS no http.proxy, definido uma vez com git config --global e restrito a um host com http.<url>.proxy; um valor vazio ou o NO_PROXY isenta servidores internos, e a configuração tem precedência sobre o https_proxy. Aplique codificação percentual à senha, prefira socks5h:// para SOCKS5, mude o http.proxyAuthMethod para basic quando o handshake for abortado e resolva erros de certificado com http.sslCAInfo, não desligando a verificação. Remotos SSH precisam de ProxyCommand ou ProxyJump. Teste cada mudança com git ls-remote antes de clonar algo grande.