Configurar proxy en Git: usar Git detrás de un proxy

Publicado:

17 min de lectura

Acar Diveroli
Autor: Acar Diveroli
Diagrama: una línea de un cliente Git cruza una elipse punteada http.proxy y va azul al remoto; un arco NO_PROXY va directo

En un portátil de trabajo recién entregado, git clone se queda parado veinte segundos y luego se rinde con Failed to connect to … :443. El navegador del mismo equipo abre la página del repositorio sin problemas, porque el navegador conoce el proxy de la empresa y Git no. Lo mismo ocurre en un servidor de compilación que solo puede salir por una pasarela, o cuando un servidor Git propio acepta conexiones de una única dirección incluida en su lista de permitidos.

Esta guía cubre http.proxy y sus ámbitos, las reglas por host, las variables de entorno que lee Git y cuál de ellas gana, SOCKS5, credenciales con caracteres especiales, remotos SSH, cómo borrar los ajustes y los textos de error exactos. Cada comando se ejecutó con Git 2.56 en Windows 11 contra pequeños proxies de prueba en 127.0.0.1, con un archivo de configuración desechable para que ningún ajuste real de Git cambiara.

¿Cuándo necesita Git un proxy?

Git necesita un proxy siempre que su red no le deja llegar al remoto directamente, o cuando el remoto solo acepta una dirección conocida: una red corporativa con proxy de salida, un runner de CI en una subred cerrada, un servidor Git propio con una sola IP en su lista de permitidos. A menudo el navegador funciona mientras Git falla, porque el navegador sigue el proxy del sistema y Git solo lee su propia configuración y unas pocas variables de entorno.

Git tiene tres formas de hablar con un remoto, y cada una toma el proxy de un sitio distinto. Antes de cambiar nada, mira la URL del remoto con git remote -v.

¿Cómo envía Git el tráfico a través de un proxy?

Git entrega los remotos HTTP y HTTPS a libcurl, la biblioteca que está detrás del comando curl, así que el tráfico HTTPS sigue el flujo habitual de un proxy:

  1. Git lee la dirección del proxy de http.<url>.proxy, luego de http.proxy y luego de las variables de entorno, y compara el host con NO_PROXY.
  2. Abre una conexión TCP con el proxy y, para un remoto https://, envía CONNECT git.example.com:443. Nuestro proxy de prueba registró exactamente esa línea, con el user agent git/2.56.0.windows.4.
  3. Si el proxy responde 407, Git repite el CONNECT con una cabecera Proxy-Authorization construida a partir de las credenciales de la URL del proxy.
  4. Tras 200 Connection established, TLS va dentro del túnel. El proxy ve el nombre de host y el puerto, no el contenido del repositorio.
  5. El servidor Git ve la IP de salida del proxy, que es justo lo que comprueba una lista de permitidos.
URL del remotoTransporteAjuste de proxy
https://git.example.com/team/app.gitHTTPS mediante libcurlhttp.proxy, variables de entorno
http://git.example.com/team/app.gitHTTP mediante 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

¿Cómo se configura un proxy en Git?

Define http.proxy con git config. El valor es una URL con la forma [protocol://][user[:password]@]proxyhost[:port], tal como la define la documentación de git-config:

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

En nuestro equipo de pruebas, el segundo comando devolvió la misma URL, y el archivo de configuración ganó una sección [http] con una línea proxy =.

En Git no existe una clave https.proxy aparte. http.proxy cubre los remotos HTTP y HTTPS, y el http:// del principio del valor describe cómo habla Git con el proxy, no con el remoto. Un proxy que espera TLS por sí mismo lleva un valor https://, y http.proxySSLCAInfo indica el paquete de certificados con el que se verifica.

Ámbito global, de sistema o de repositorio

La opción decide qué archivo recibe la línea:

  • --global escribe en ~/.gitconfig y se aplica a todos los repositorios de tu cuenta de usuario.
  • --system escribe en el archivo etc/gitconfig de la instalación y se aplica a todos los usuarios del equipo.
  • --local, el valor por defecto cuando no indicas ninguna opción, escribe en .git/config y solo afecta al repositorio actual.

Cuando la misma clave aparece en varios archivos, el valor del repositorio gana al global, y el global gana al del sistema. Un compañero que «ya configuró el proxy» pero sigue sin poder clonar muchas veces ejecutó el comando dentro de un solo repositorio, sin --global.

Solo para un comando

Para probar un proxy sin guardar nada, pásalo con -c antes del subcomando:

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

git ls-remote solo enumera las ramas de un remoto, así que es una prueba de conectividad rápida e inofensiva.

¿Cómo se usa un proxy solo para un host?

Escribe la dirección del remoto dentro de la clave: http.<url>.proxy. Git compara cada URL de petición con estas claves y usa la coincidencia más precisa, de modo que un mismo equipo puede llegar a un host externo por el proxy y a uno interno de forma directa:

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

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

Un valor vacío desactiva el proxy para esa dirección. En nuestra prueba, el host excluido recibió la conexión directa aunque http.proxy y la variable https_proxy apuntaban a un proxy, y git config --get-urlmatch http.proxy <url> devolvió una línea vacía para él y el proxy para cualquier otro host.

La comparación sigue un orden fijo: esquema, host, puerto, ruta y nombre de usuario. Un * en el host equivale a un solo nivel de subdominios (https://*.example.com cubre git.example.com, pero no a.b.example.com), y una ruta más larga gana a una más corta. Un remoto también puede llevar su propio remote.origin.proxy; una cadena vacía ahí desactiva el proxy para ese remoto.

¿Usa Git HTTP_PROXY, HTTPS_PROXY y NO_PROXY?

Sí. Cuando http.proxy no está definido, Git toma el proxy de las mismas variables de entorno que curl: https_proxy para los remotos HTTPS, http_proxy para los remotos HTTP y all_proxy como alternativa para ambos. NO_PROXY contiene una lista de hosts separados por comas que deben conectarse sin proxy.

Configuramos las variables y la configuración con dos proxies de prueba distintos y observamos cuál recibía el CONNECT:

ConfiguraciónResultado
https_proxy y http.proxy definidosSe usó http.proxy
Solo HTTPS_PROXY (en mayúsculas)Se usó el proxy
Solo HTTP_PROXY, remoto HTTPSConexión directa
Solo all_proxySe usó el proxy
http.proxy más NO_PROXY=.internal.testConexión directa

Dos filas sorprenden a mucha gente. HTTP_PROXY por sí solo no hace nada con un remoto HTTPS, así que el clon sale directo. Y NO_PROXY también excluye hosts de un proxy definido en la configuración de Git: útil para servidores internos, confuso cuando queda un valor antiguo en el perfil de tu shell. Sus entradas coinciden con el propio host o con cualquier host bajo ese dominio, por lo que internal.test también cubre git.internal.test.

En Linux y macOS importan las mayúsculas. La documentación de curl sobre proxies explica que http_proxy solo se lee en minúsculas, porque un servidor web que ejecuta un script CGI convierte una cabecera entrante Proxy: en una variable HTTP_PROXY en mayúsculas; las demás variables de proxy funcionan de las dos maneras. En nuestro equipo Windows también funcionó la forma en mayúsculas, ya que Windows no distingue mayúsculas de minúsculas en los nombres de variables.

¿Cómo se usa un proxy SOCKS5 con Git?

Escribe un esquema SOCKS en la misma clave http.proxy. libcurl acepta socks4://, socks4a://, socks5:// y socks5h://, y la diferencia entre los dos últimos está en dónde se resuelve el nombre de host:

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

Con socks5://, Git busca la dirección IP del remoto en tu equipo y pide al proxy que se conecte a ese número. Con socks5h://, envía el nombre de host y es el proxy quien lo resuelve. Nuestro servidor SOCKS de prueba hizo visible la diferencia: el mismo ls-remote llegó como CONNECT IPv4 104.20.23.154 port 443 con socks5:// y como CONNECT DOMAIN example.com port 443 con socks5h://.

Usa socks5h:// cuando tu red no pueda resolver nombres externos o cuando las consultas DNS no deban salir desde tu equipo. La referencia de libcurl sobre proxies señala además que una URL de proxy sin puerto usa 1080 por defecto, así que escribe siempre el puerto de tu endpoint.

Un endpoint de Proxies SOCKS5 encaja en la misma clave.

El funcionamiento del protocolo paso a paso se explica en ¿Qué es un proxy SOCKS5?.

¿Cómo se pasan las credenciales del proxy de forma segura?

Pon el nombre de usuario y la contraseña en la URL del proxy y aplica codificación porcentual a cualquier carácter que tenga significado en una URL. Los más comunes son @ como %40, : como %3A, # como %23, / como %2F y un espacio como %20:

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

En nuestro proxy de prueba, la forma codificada llegó como user:p@ss:w#rd, tal como se pretendía. La forma sin codificar, http://user:p@ss:w#rd@…, nunca llegó al proxy: Git se detuvo con Invalid proxy URL … only SOCKS proxies support paths, porque la primera @ y el # partieron la URL.

Una contraseña en ~/.gitconfig se guarda en texto plano, así que hay dos opciones más limpias. Deja fuera la contraseña (http://user@pr.proxynet.io:8000) y Git te la pedirá mediante su sistema de credenciales, el mismo que guarda los inicios de sesión de los repositorios; con las peticiones interactivas desactivadas, nuestra ejecución se detuvo con could not read Password … terminal prompts disabled. O prescinde por completo de las credenciales: cuando la IP del equipo está en la lista de IP autorizadas del proxy, la URL es simplemente http://pr.proxynet.io:8000. Proxynet admite hasta 10 IP en esa lista, algo que encaja con un servidor de compilación de dirección fija.

¿anyauth o basic?

http.proxyAuthMethod decide cómo se autentica Git. El valor por defecto, anyauth, envía primero el CONNECT sin credenciales y espera un 407 que indique los métodos aceptados; basic envía el usuario y la contraseña con la primera petición. Nuestros proxies de prueba mostraron cuándo importa:

Comportamiento del proxyanyauth (por defecto)basic
407 con desafío, conexión abiertaFunciona, dos peticionesFunciona, una petición
407 con desafío, luego cierraProxy CONNECT abortedFunciona
407 sin Proxy-Authenticateresponse 407Funciona

Si ves Proxy CONNECT aborted con la contraseña correcta, prueba primero git config --global http.proxyAuthMethod basic. Basic envía la contraseña codificada en base64, no cifrada, así que úsalo solo en redes de confianza.

¿Funciona http.proxy con remotos SSH?

No. Un remoto como git@git.example.com:team/app.git funciona por SSH, y Git lanza el programa ssh para él; http.proxy y las variables de proxy no se consultan nunca. Con http.proxy definido, nuestra prueba SSH ignoró el proxy por completo y falló con ssh: Could not resolve hostname. Si SSH es nuevo para ti, ¿Qué es SSH? explica las claves y la verificación del host.

SSH tiene dos opciones de proxy propias, descritas en el manual de ssh_config:

  • ProxyCommand ejecuta un programa auxiliar que abre la conexión a través de un proxy; %h y %p representan el host y el puerto de destino. El nc de OpenBSD presente en muchos sistemas Linux y macOS hace justo eso: ProxyCommand nc -X connect -x pr.proxynet.io:8000 %h %p para un proxy HTTP, -X 5 para SOCKS5. Su manual indica que la autenticación con el proxy solo funciona con proxies HTTP CONNECT, así que aquí la lista de IP autorizadas es el camino más sencillo.
  • ProxyJump envía la conexión a través de otro servidor SSH (un host de salto o bastión) en lugar de un proxy web: ProxyJump user@jump.example.com.

Coloca la línea bajo un bloque Host en ~/.ssh/config para que solo la use el servidor Git:

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

Para un solo repositorio o un solo comando, pasa la opción mediante core.sshCommand o la variable GIT_SSH_COMMAND. En nuestro equipo de pruebas usamos connect, un pequeño programa auxiliar que estaba presente en el entorno Git de ese equipo, y los proxies registraron CONNECT DOMAIN git.internal.test port 22 (SOCKS5) y CONNECT git.internal.test:22 (HTTP). Algunos proxies HTTP solo permiten CONNECT al puerto 443, así que comprueba que el puerto 22 esté permitido o cambia el remoto a HTTPS. El antiguo protocolo git:// tiene su propio ajuste, core.gitProxy, que hoy rara vez hace falta.

¿Cómo se comprueban y se eliminan los ajustes de proxy de Git?

Primero lee el valor, incluido su origen. Estos comandos responden a la mayoría de las preguntas del tipo «¿por qué Git sigue usando el proxy antiguo?»:

bash
git config --get http.proxy                     # valor que usa Git en este repositorio
git config --show-origin --get-all http.proxy   # cada valor y el archivo donde está
git config --get-urlmatch http.proxy https://git.example.com/team/app.git
env | grep -i proxy                             # variables (PowerShell: Get-ChildItem env:*proxy*)

Elimina un valor con --unset en el mismo ámbito en el que lo definiste:

bash
git config --global --unset http.proxy
git config --global --unset http.https://git.example.com.proxy
git config --global --unset-all http.proxy      # si la clave aparece más de una vez

Si una clave se añadió dos veces, --unset a secas se niega con warning: http.proxy has multiple values; --unset-all borra ambas entradas. Elimina las variables con unset https_proxy en bash o Remove-Item Env:https_proxy en PowerShell, y borra la línea del perfil que las definía.

Para ver la conversación con el proxy, ejecuta un comando con GIT_TRACE_CURL=1. Git oculta por defecto la cabecera Proxy-Authorization en esa traza, pero trata la salida como información sensible de todos modos.

¿Qué proxy encaja con el tráfico de Git?

Un proxy con dirección de salida fija es lo que mejor encaja con Git, porque el motivo habitual para pasar Git por un proxy de terceros es una lista de permitidos en el servidor Git, en un espejo de paquetes o en la red de un socio. Los Proxies de centro de datos ofrecen una dirección IPv4 dedicada que no cambia entre clones ni reinicios, así que la entrada en la lista de permitidos se escribe una sola vez; las direcciones rotativas van en contra de ese objetivo.

Los productos que se venden por IP, como los proxies de centro de datos, incluyen por defecto una restricción de sitios de destino, y el acceso a todos los sitios web es un complemento de pago, así que comprueba que tu host Git sea accesible con tus IP antes de integrarlo en la CI. En una red corporativa, la respuesta correcta sigue siendo el proxy que gestiona tu equipo de TI.

Dónde te encuentras con los ajustes de proxy de Git

Los portátiles corporativos son el caso clásico: cada conexión saliente pasa por un proxy que inspecciona el tráfico, y a Git se le indica una vez en la configuración global. Después vienen los runners de CI, normalmente mediante variables de entorno en la definición del trabajo, para que Git, el gestor de paquetes y curl compartan un mismo ajuste. Los servidores Git propios y los espejos de artefactos que aceptan una lista corta de direcciones de origen necesitan una IP de salida estable, y los equipos que trabajan a través de un bastión se topan con la parte SSH, donde ProxyJump sustituye a cualquier proxy web.

Errores comunes de proxy en Git y cómo solucionarlos

Los textos siguientes son los que Git 2.56 con libcurl 8.23 mostró en nuestro equipo de pruebas después de fatal: unable to access '<url>':. Las versiones antiguas de curl redactan algunos de forma ligeramente distinta.

  • Failed to connect to git.example.com:443 over proxy 127.0.0.1 after 0 ms: Could not connect to server. No se puede llegar al propio proxy: puerto equivocado, un cortafuegos o el proxy está caído.
  • El mismo mensaje sin over proxy. Git no usó ningún proxy. Revisa --show-origin --get-all http.proxy, el esquema de la URL y NO_PROXY.
  • Could not resolve proxy: proxy.invalid. El nombre de host del proxy no se resuelve.
  • Could not resolve host: git.example.com. Git salió directo, o un proxy socks5:// necesita una resolución que tu red no puede hacer. Define el proxy o usa socks5h://.
  • CONNECT tunnel failed, response 407. El proxy rechazó las credenciales o no recibió ninguna. Revisa el nombre de usuario, la codificación de la contraseña y la lista de IP autorizadas; Cómo solucionar HTTP 407 Proxy Authentication Required repasa todas las causas.
  • Proxy CONNECT aborted. Suele ser la negociación anyauth fallando en un proxy que cierra la conexión tras su 407. Pon http.proxyAuthMethod en basic.
  • Invalid proxy URL … only SOCKS proxies support paths. Hay una @, un # o una / sin codificar en la contraseña.
  • cannot complete SOCKS5 connection to … (2). El proxy SOCKS rechazó el destino; el número es el código de respuesta SOCKS (2 significa «no permitido por las reglas»).
  • SSL certificate problem: unable to get local issuer certificate. Un proxy que inspecciona TLS vuelve a firmar el tráfico con un certificado de la empresa en el que Git no confía. Haz que http.sslCAInfo apunte a un paquete con el certificado raíz de la empresa o, en Git for Windows, pon http.sslBackend en schannel para usar el almacén de certificados de Windows.
  • Una espera larga que termina en un tiempo de espera agotado. Un cortafuegos descarta los paquetes, normalmente porque Git sale directo en una red que solo permite pasar por el proxy.

http.sslVerify false y GIT_SSL_NO_VERIFY ocultan el error de certificado desactivando la comprobación que te protege de un ataque de intermediario (man-in-the-middle). Úsalos como mucho para un único comando de diagnóstico, nunca como solución.

Guía de decisión

NecesidadRecomendación
Todos los remotos HTTPS por un proxygit config --global http.proxy
Solo un host externohttp.<url>.proxy
El servidor interno debe ir directohttp.<url>.proxy vacío o NO_PROXY
Trabajo de CI con varias herramientasVariables https_proxy y NO_PROXY
SOCKS5 con DNS en el proxysocks5h:// en http.proxy
Sin contraseña en archivos de configuraciónLista de IP autorizadas o solo el usuario
Proxy CONNECT abortedhttp.proxyAuthMethod basic
Remotos git@ o ssh://ProxyCommand o ProxyJump
Inspección TLS de la empresahttp.sslCAInfo o schannel

Preguntas frecuentes

¿Cómo configuro un proxy en Git?

Ejecuta git config --global http.proxy http://host:port, con user:pass@ delante del host si el proxy exige inicio de sesión. Se aplica a todos los remotos HTTP y HTTPS de tu cuenta; compruébalo con git config --global --get http.proxy.

¿Cómo quito el proxy de Git?

Ejecuta git config --global --unset http.proxy, con la misma opción de ámbito que usaste para definirlo. Si Git sigue usando un proxy, busca un valor de repositorio con git config --show-origin --get-all http.proxy y revisa si hay https_proxy o all_proxy en tu entorno.

¿Existe un ajuste https.proxy en git config?

No. La documentación de Git solo define http.proxy, y esa única clave cubre los remotos HTTP y HTTPS. Para un solo host HTTPS, usa http.https://host.proxy.

¿Cómo uso un proxy SOCKS5 con Git?

Asigna a http.proxy el valor socks5h://user:pass@host:port; la h hace que el proxy resuelva los nombres de host. Esto cubre los remotos HTTPS, mientras que los remotos SSH necesitan ProxyCommand con un programa auxiliar compatible con SOCKS, como nc -X 5.

¿Usa Git la configuración de proxy de Windows?

No cuentes con ello. La documentación de Git solo menciona como fuentes de proxy sus propias claves http.proxy y la familia de variables https_proxy. Define http.proxy de forma explícita y prueba con git ls-remote.

¿Por qué git clone por SSH ignora mi proxy?

Porque http.proxy solo afecta a los remotos HTTP y HTTPS. Los remotos SSH necesitan una línea ProxyCommand o ProxyJump en ~/.ssh/config o en core.sshCommand; como alternativa, clona la URL HTTPS del mismo repositorio.

En resumen

Git toma su proxy HTTPS de http.proxy, que se define una vez con git config --global y se limita a un host con http.<url>.proxy; un valor vacío o NO_PROXY excluye los servidores internos, y la configuración tiene prioridad sobre https_proxy. Codifica la contraseña con codificación porcentual, prefiere socks5h:// para SOCKS5, cambia http.proxyAuthMethod a basic cuando la negociación se interrumpe y resuelve los errores de certificado con http.sslCAInfo, no desactivando la verificación. Los remotos SSH necesitan ProxyCommand o ProxyJump. Prueba cada cambio con git ls-remote antes de clonar algo grande.