HOWTO · Git

Configurar un proxy para trabajar con Git

En este artículo, discutiremos el proceso de configuración de Git para que funcione con diferentes proxies.

En esta página

Cuando un firewall corporativo bloquea el tráfico de Git, configura Git para que envíe las solicitudes a través del proxy de tu organización. Puedes aplicar un proxy a un solo comando, guardarlo en el repositorio actual o guardarlo de forma global para tu usuario. Los ejemplos usan nombres de host y credenciales reservados para documentación; sustitúyelos por los valores que te proporcione el administrador de red.

Elige un protocolo y un ámbito para el proxy

HTTP, HTTPS, SOCKS4 y SOCKS5 identifican esquemas de URL u opciones de protocolo del proxy. La URL de destino y la URL del proxy describen conexiones distintas: por ejemplo, Git puede acceder a un destino https:// a través de un proxy http://. No tienen que coincidir.

Usa git -c http.proxy=PROXY_URL COMMAND para establecer un proxy para un solo comando de Git. La configuración local del repositorio se aplica al repositorio actual, mientras que --global guarda una configuración a nivel de usuario de Git y afecta a tus repositorios. El administrador también puede proporcionar una configuración a nivel de sistema. Las configuraciones aplicables más específicas pueden prevalecer sobre las más generales; por eso, consulta el valor efectivo si el comportamiento no coincide con lo que esperas.

Las URL de proxy que contienen nombres de usuario o contraseñas pueden requerir codificación URL para los caracteres reservados. Evita incluir credenciales reales en comandos compartidos, scripts o el historial de la shell. Si está disponible, usa un gestor de credenciales aprobado o el método de tu organización para gestionar secretos.

Configura un proxy HTTP

Para una sola operación, añade el proxy con la opción -c de Git. Por ejemplo, el comando en línea git -c http.proxy=http://proxy.example:8080 clone https://git.example/team/project.git aplica el proxy únicamente a ese clon. Sustituye el host y el puerto del proxy por los que te proporcione el administrador.

También puedes configurar un proxy solo para una URL de destino coincidente mediante la clave específica de URL http.https://git.example.proxy. Esto resulta útil si otros hosts de Git deben conectarse directamente o usar un proxy distinto. El patrón de URL se compara según las reglas de configuración de URL de Git, así que usa el esquema y el host del destino al que accedes realmente.

Ejecuta este ejemplo con un archivo de configuración temporal de Git. Guarda un valor de muestra para el proxy HTTP y luego lo consulta; no modifica la configuración del repositorio ni la de tu usuario.

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

set -eu
config_file="$(mktemp)"
trap 'rm -f "$config_file"' EXIT
git config --file "$config_file" http.proxy http://proxy.example:8080
git config --file "$config_file" --get http.proxy

Configura un proxy HTTPS para el tráfico de Git

Para un destino HTTPS, configura el proxy para ese destino, por ejemplo, con http.https://git.example.proxy. El proxy puede seguir usando una URL http://: esta describe la conexión de Git al proxy, mientras que HTTPS describe la conexión con el destino. Si el punto de acceso del proxy admite TLS, usa el esquema de proxy HTTPS que haya indicado el administrador.

Un error como unable to access 'https://...': Unknown SSL protocol error in connection to ...:443 puede ser una pista de que la negociación entre el proxy y el destino no se está realizando como se esperaba. Primero, comprueba el esquema, el host y el puerto del proxy, así como las reglas del firewall. Si el proxy intercepta TLS, configura Git para que confíe en la autoridad de certificación que proporciona tu organización, siguiendo la configuración de certificados documentada para tu entorno. No desactives la verificación de certificados como solución habitual: hacerlo elimina la protección frente a conexiones no confiables o interceptadas. Si el administrador te pide usar temporalmente una excepción de verificación para diagnosticar el problema, limítala a un solo comando y restablece la verificación normal inmediatamente después.

Guarda la configuración del proxy en Git

Para guardar un proxy en el repositorio actual, ejecuta git config http.proxy http://proxy.example:8080 desde ese repositorio. Para guardar la misma configuración para tu usuario en todos los repositorios, usa git config --global http.proxy http://proxy.example:8080. Estas configuraciones permanecen activas hasta que las cambies o elimines. También puedes guardar un valor específico para un destino con git config --global http.https://git.example.proxy http://proxy.example:8080.

La clave http.proxy es una opción de configuración de Git; --global es una opción de línea de comandos que selecciona el ámbito del usuario. Usa la configuración local del repositorio cuando solo una copia de trabajo necesite el proxy, y la configuración global cuando la misma ruta de red se aplique en general a tu trabajo con Git. Consulta con el administrador antes de guardar credenciales en cualquiera de estos ámbitos, ya que los archivos de configuración se pueden copiar o incluir en copias de seguridad.

Consulta y elimina la configuración del proxy

Muestra las opciones relacionadas con HTTP y su procedencia con git config --show-origin --get-regexp '^http\.'. El comando git config --get http.proxy consulta únicamente el valor genérico de http.proxy. Para consultar el valor efectivo del proxy aplicable a un destino HTTPS, usa git config --get-urlmatch http.proxy https://git.example y sustituye la URL por el destino al que necesitas acceder. Si no aparece ningún resultado, significa que no se encontró un valor que coincida con esa consulta; otros ámbitos de configuración aún podrían proporcionar uno.

Elimina un proxy local del repositorio con git config --unset-all http.proxy. Para eliminar uno global, usa git config --global --unset-all http.proxy. Si se trata de una entrada específica para un destino, sustituye la clave por la clave configurada exacta, por ejemplo, http.https://git.example.proxy. Si añadiste una excepción de verificación SSL, elimina también esa clave en el mismo ámbito, por ejemplo, con git config --unset-all http.sslVerify o git config --global --unset-all http.sslVerify.

Eliminar una clave no borra todas las configuraciones del proxy. Vuelve a consultar los ámbitos del repositorio y global, y elimina por separado las entradas específicas de URL. --unset-all elimina todos los valores de esa clave en el ámbito seleccionado; no modifica la configuración más general, más específica ni la del sistema.

Configura un proxy SOCKS en Git

Las URL de proxy de Git pueden usar socks4:// o socks5:// si el servicio admite ese protocolo. Para una operación de un solo comando, puedes usar una forma como git -c http.proxy=socks5://proxy.example:1080 fetch. Para guardar un proxy general SOCKS5 para tu usuario, ejecuta git config --global http.proxy socks5://proxy.example:1080; para un destino HTTPS concreto, usa git config --global http.https://git.example.proxy socks5://proxy.example:1080.

Elige SOCKS4 o SOCKS5 según el servicio y la compatibilidad de autenticación que haya configurado tu organización. Escribe el esquema exactamente, usa el puerto asignado y consulta la configuración de Git si una solicitud sigue evitando el proxy o no logra conectarse.