Proxies para GitLab: cómo configurar el acceso para el equipo y los pipelines de CI/CD sin interrupciones

```html

GitLab es una plataforma popular para almacenar código y gestionar procesos de DevOps, utilizada por miles de equipos en todo el mundo. Pero, ¿qué hacer si el acceso a GitLab está bloqueado a nivel de proveedor, en una red corporativa o en todo un país? Y aún peor, cuando el pipeline de CI/CD falla en medio de la noche simplemente porque el runner no puede acceder al repositorio.

En este artículo, analizaremos cómo configurar un proxy para GitLab a nivel del cliente Git, GitLab Runner y servidor corporativo, de modo que todo el equipo trabaje de manera estable desde cualquier parte del mundo.

¿Por qué se necesita un proxy para GitLab: escenarios reales?

Antes de configurar un proxy, es importante entender qué problema específico estás resolviendo. Las situaciones pueden variar, y de ello depende la elección del tipo de proxy y la forma de conectarlo.

Escenario 1: GitLab está bloqueado por el proveedor o a nivel nacional

En varios países y redes corporativas, el acceso a gitlab.com está restringido. Un desarrollador abre la terminal, escribe git pull — y recibe un timeout. En este caso, el proxy actúa como intermediario: el tráfico no va directamente a gitlab.com, sino a través de un servidor intermedio en un país donde no hay restricciones.

Escenario 2: Equipo distribuido en diferentes países

Imagina: parte del equipo trabaja desde Rusia, parte desde Kazajistán, parte desde Europa. Cada uno tiene diferentes condiciones de red y diferentes restricciones. Para que todos trabajen de manera estable y con la misma velocidad, las empresas implementan un servidor proxy corporativo a través del cual todo el tráfico hacia GitLab fluye por un único canal.

Escenario 3: El runner de CI/CD no puede acceder a dependencias externas

GitLab Runner inicia un pipeline, y en la etapa npm install o pip install todo falla — porque el servidor en el que se ejecuta el runner está en una red cerrada sin acceso directo a Internet. El proxy permite que el runner obtenga dependencias externas sin abrir acceso completo a Internet para todo el servidor.

Escenario 4: GitLab autoalojado detrás de un firewall corporativo

La empresa mantiene su propio servidor GitLab en la red interna. Los desarrolladores en remoto deben conectarse a él. En lugar de usar VPN para todo el tráfico, se puede configurar un proxy solo para el tráfico de GitLab — es más rápido y más fácil de administrar.

Escenario 5: Monitoreo y auditoría del tráfico

Las grandes empresas dirigen todo el tráfico hacia los repositorios a través de un proxy corporativo para registrar la actividad, controlar quién y qué se está enviando, y bloquear operaciones no deseadas. Este es un requisito de seguridad, no una forma de eludir bloqueos.

Es importante entender antes de la configuración:

El proxy para GitLab puede ser necesario en tres niveles simultáneamente: en la máquina del desarrollador (cliente Git), en el servidor con GitLab Runner (CI/CD), y en el propio servidor GitLab (si es autoalojado). Cada nivel se configura por separado.

Qué tipo de proxy es adecuado para GitLab

GitLab opera a través de los protocolos HTTPS y SSH. Esto determina de inmediato qué tipos de proxy son aplicables y cuáles no. Analicemos las opciones.

Tipo de proxy	Protocolo	Adecuado para GitLab	Cuándo usar
Proxy HTTP/HTTPS	HTTP, HTTPS	✓ Sí	Git sobre HTTPS, interfaz web de GitLab
Proxy SOCKS5	TCP (cualquiera)	✓ Sí (mejor opción)	Git sobre HTTPS y SSH, CI/CD
Proxy SOCKS4	TCP	~ Parcialmente	Solo si no hay SOCKS5
Proxy transparente	HTTP	✗ No	No es adecuado — no elude bloqueos

Para trabajar con GitLab, la elección óptima es SOCKS5. Funciona a nivel TCP, por lo que proxy tanto las conexiones HTTPS (interfaz web, git clone por HTTPS) como las conexiones SSH (git push/pull por SSH en el puerto 22 o 443).

Proxies residenciales vs de centros de datos para GitLab

Aquí todo depende de la tarea. Si el objetivo es eludir bloqueos por GeoIP o obtener una IP estable para la autenticación, son adecuados proxies de centros de datos — son más rápidos, más baratos y proporcionan baja latencia, lo cual es crítico al trabajar con grandes repositorios.

Sin embargo, si tu IP corporativa ha sido incluida en la lista de bloqueos de GitLab (lo cual puede ocurrir tras un escaneo agresivo o después de incidentes de seguridad), entonces deberías considerar proxies residenciales — sus direcciones IP pertenecen a usuarios domésticos reales y rara vez son bloqueadas por las plataformas.

Configuración del proxy para el cliente Git (globalmente)

Este es el escenario más común: un desarrollador en su máquina no puede conectarse a GitLab. La configuración se realiza a través de la configuración del propio Git — una vez, y funciona para todos los repositorios.

Opción A: Proxy HTTPS para Git

Si trabajas con GitLab a través de HTTPS (la dirección del repositorio comienza con https://), ejecuta en la terminal:

# Configurar proxy HTTP globalmente
git config --global http.proxy http://SU_IP_PROXY:PUERTO

# Si el proxy requiere autenticación
git config --global http.proxy http://USUARIO:CONTRASEÑA@SU_IP_PROXY:PUERTO

# Para proxy SOCKS5 (recomendado)
git config --global http.proxy socks5://SU_IP_PROXY:PUERTO

# Verificar que la configuración se aplicó
git config --global --get http.proxy

Opción B: Proxy solo para gitlab.com (no afecta a otros repositorios)

Si no deseas que el proxy se aplique a todas las operaciones de Git (por ejemplo, GitHub o Bitbucket funcionan normalmente), puedes configurar el proxy solo para un dominio específico:

# Proxy solo para gitlab.com
git config --global http.https://gitlab.com.proxy socks5://SU_IP_PROXY:PUERTO

# O para tu GitLab autoalojado
git config --global http.https://git.tuempresa.com.proxy socks5://SU_IP_PROXY:PUERTO

Opción C: SSH a través de proxy (para quienes trabajan por SSH)

Si clonas repositorios por SSH ([email protected]:...), la configuración del proxy se realiza en el archivo de configuración SSH, no en Git. Abre el archivo ~/.ssh/config y añade:

# Para Linux/macOS — a través de nc (netcat)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand nc -X 5 -x SU_IP_PROXY:PUERTO %h %p

# Para Windows — a través de connect.exe (Git para Windows)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand connect -S SU_IP_PROXY:PUERTO %h %p

Después de la configuración, verifica la conexión con el comando ssh -T [email protected]. Si todo está configurado correctamente, verás un mensaje de bienvenida de GitLab.

Cómo desactivar el proxy cuando ya no es necesario

# Eliminar el proxy global
git config --global --unset http.proxy

# Eliminar el proxy para un dominio específico
git config --global --unset http.https://gitlab.com.proxy

Proxy para GitLab Runner y pipelines de CI/CD

GitLab Runner es un agente que ejecuta tareas desde .gitlab-ci.yml. Si el runner se encuentra en una red cerrada o en un servidor con acceso limitado a Internet, es necesario configurar el proxy por separado. Las configuraciones del cliente Git del desarrollador no ayudarán aquí — el runner opera en otra máquina.

Método 1: Variables de entorno en la configuración del runner

Abre el archivo de configuración de GitLab Runner (normalmente /etc/gitlab-runner/config.toml) y añade las variables de entorno en la sección [runners.env]:

[[runners]]
  name = "mi-runner"
  url = "https://gitlab.com/"
  token = "SU_TOKEN"
  executor = "shell"
  environment = [
    "HTTP_PROXY=http://SU_IP_PROXY:PUERTO",
    "HTTPS_PROXY=http://SU_IP_PROXY:PUERTO",
    "NO_PROXY=localhost,127.0.0.1,tu-dominio-interno.com"
  ]

Después de modificar la configuración, reinicia el runner: sudo gitlab-runner restart

Método 2: Variables en .gitlab-ci.yml (a nivel de pipeline)

Si no eres el administrador del runner o deseas configurar el proxy solo para un proyecto específico, añade las variables directamente en el archivo del pipeline:

variables:
  HTTP_PROXY: "http://SU_IP_PROXY:PUERTO"
  HTTPS_PROXY: "http://SU_IP_PROXY:PUERTO"
  NO_PROXY: "localhost,127.0.0.1,.internal.company.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - npm install   # ahora irá a través del proxy
    - npm run build

Método 3: Variables en la configuración del proyecto GitLab (sin commit en el repositorio)

La mejor manera para datos sensibles (proxy con autenticación): ve a Settings → CI/CD → Variables de tu proyecto y añade las variables HTTP_PROXY, HTTPS_PROXY, NO_PROXY como variables protegidas (masked). Estarán disponibles automáticamente en todos los pipelines, pero no serán visibles en los logs.

Proxy para el executor de Docker

Si el runner utiliza el executor de Docker, los contenedores por defecto no heredan la configuración del proxy del host. Es necesario añadir las variables en config.toml en la sección [runners.docker], o crear un archivo /etc/systemd/system/docker.service.d/proxy.conf en el host con el runner:

[Service]
Environment="HTTP_PROXY=http://SU_IP_PROXY:PUERTO"
Environment="HTTPS_PROXY=http://SU_IP_PROXY:PUERTO"
Environment="NO_PROXY=localhost,127.0.0.1"

Después de esto: sudo systemctl daemon-reload && sudo systemctl restart docker

Proxy para servidor GitLab autoalojado

Si administras tu propio servidor GitLab (instalado a través de Omnibus o Helm), el proxy es necesario para que GitLab pueda acceder a servicios externos: enviar notificaciones, conectarse a sistemas CI externos, cargar avatares de usuarios, integrarse con Jira o Slack.

Configuración en gitlab.rb (instalación Omnibus)

Abre el archivo /etc/gitlab/gitlab.rb y añade o descomenta las siguientes líneas:

# Proxy para GitLab (Omnibus)
gitlab_rails['env'] = {
  "http_proxy" => "http://SU_IP_PROXY:PUERTO",
  "https_proxy" => "http://SU_IP_PROXY:PUERTO",
  "no_proxy" => "localhost,127.0.0.1,SU_DOMINIO_INTERNO"
}

# Si el proxy requiere autenticación:
gitlab_rails['env'] = {
  "http_proxy" => "http://USUARIO:CONTRASEÑA@SU_IP_PROXY:PUERTO",
  "https_proxy" => "http://USUARIO:CONTRASEÑA@SU_IP_PROXY:PUERTO",
  "no_proxy" => "localhost,127.0.0.1"
}

Después de modificar la configuración, aplica los ajustes: sudo gitlab-ctl reconfigure

Configuración de conexiones salientes a través del área de administración

En GitLab 15.0+ se introdujo la posibilidad de configurar el proxy directamente a través de la interfaz web: ve a Admin Area → Settings → Network → Outbound requests. Aquí puedes especificar un proxy para los webhooks salientes y restringir los rangos de IP a los que GitLab puede acceder. Esto es útil para la seguridad — previene ataques SSRF a través de webhooks.

Organización del acceso para todo el equipo a través del proxy

Cuando es necesario garantizar un acceso estable a GitLab para un equipo de 5 a 50 personas, la configuración individual en cada máquina no es el mejor enfoque. Consideremos soluciones más escalables.

Enfoque 1: Servidor proxy corporativo

Se despliega un único servidor proxy (por ejemplo, Squid o 3proxy) con acceso a Internet. Todos los desarrolladores configuran Git para usar este servidor. Ventajas: gestión centralizada, un único punto de control, se puede registrar el tráfico. Desventaja: el servidor se convierte en un único punto de fallo.

Enfoque 2: Espejo (mirror) del repositorio

GitLab admite la replicación de repositorios. Se puede configurar un GitLab autoalojado en la red interna como espejo de gitlab.com. Los desarrolladores trabajan con el servidor interno, que se sincroniza con el externo a través del proxy. Esto reduce la dependencia de la calidad de la conexión proxy para cada desarrollador.

Enfoque 3: Configuración automática a través de dotfiles o script de onboarding

Para equipos donde cada desarrollador configura su entorno, es conveniente crear un script de onboarding que configure automáticamente los ajustes necesarios de Git. El script se almacena en un repositorio corporativo y se ejecuta al configurar un nuevo lugar de trabajo.

#!/bin/bash
# setup-git-proxy.sh — ejecutar al configurar un nuevo lugar de trabajo

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

echo "Configurando el proxy de Git para acceder a GitLab..."
git config --global http.https://gitlab.com.proxy "socks5://${PROXY_HOST}:${PROXY_PORT}"
git config --global http.sslVerify true
echo "¡Listo! Verifica: git config --global --list | grep proxy"

Lista de verificación para el despliegue en equipo

• Determinar si se necesita un proxy a nivel de desarrolladores, runners o servidor GitLab (o los tres)
• Elegir el tipo de proxy: SOCKS5 para máxima compatibilidad
• Configurar NO_PROXY para todos los dominios y servicios internos
• Verificar el funcionamiento de las claves SSH a través del proxy (¡paso separado!)
• Documentar la configuración en la wiki corporativa
• Crear un script de onboarding para nuevos empleados
• Configurar el monitoreo de la disponibilidad del servidor proxy

Problemas comunes y sus soluciones

Incluso después de una configuración correcta, a veces algo sale mal. Aquí están los problemas más comunes y cómo diagnosticarlos.

Problema 1: Problema de certificado SSL: no se puede obtener el certificado del emisor local

Este error ocurre cuando el servidor proxy (especialmente el corporativo) realiza inspección SSL — reemplaza el certificado de GitLab por el suyo. Git no confía en este certificado. Solución: añadir el certificado raíz corporativo a los confiables.

# Solución temporal (para depuración, no para producción!)
git config --global http.sslVerify false

# Solución correcta: añadir el certificado corporativo
git config --global http.sslCAInfo /ruta/al/corporate-ca-bundle.crt

Problema 2: El proxy funciona para HTTPS, pero SSH no funciona

Esta es una situación clásica: configuraste http.proxy en Git, la clonación por HTTPS funcionó, pero las operaciones SSH aún no pasan. La razón: el tráfico SSH no pasa a través del proxy HTTP. Necesitas configurar ~/.ssh/config como se describe en la sección sobre el cliente Git.

Alternativa: cambiar a trabajar con GitLab a través de HTTPS en lugar de SSH. Para ello, cambia la URL remota:

# Verificar el remoto actual
git remote -v

# Cambiar de SSH a HTTPS
git remote set-url origin https://gitlab.com/usuario/repo.git

Problema 3: El pipeline de CI/CD se queda atascado en la etapa de clonación del repositorio

El runner clona el repositorio directamente desde GitLab, utilizando un token. Si el runner está detrás de un proxy, esta clonación también debe realizarse a través del proxy. Asegúrate de que las variables HTTP_PROXY y HTTPS_PROXY estén establecidas en config.toml, y no solo en .gitlab-ci.yml — las variables del archivo CI se aplican después de la clonación, no antes.

Problema 4: El proxy funciona, pero muy lentamente

Si push/pull funcionan, pero tardan de 5 a 10 veces más de lo habitual, el problema puede estar en el ancho de banda del servidor proxy o en su ubicación geográfica. Para trabajar con grandes repositorios (más de 100 MB) es importante elegir un proxy con baja latencia y alto ancho de banda. Los proxies de centros de datos son preferibles en este caso a los residenciales — proporcionan un canal más estable.

Problema 5: La autenticación a través del proxy requiere volver a ingresar la contraseña

Si el proxy requiere autenticación básica, y Git solicita la contraseña cada vez, configura el helper de credenciales:

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

# Windows — usar el Administrador de Credenciales de Windows
git config --global credential.helper manager

# Linux — almacenar en caché durante 1 hora
git config --global credential.helper "cache --timeout=3600"

Conclusión y recomendaciones

Configurar un proxy para GitLab es una tarea que se resuelve en varios niveles simultáneamente. Al desarrollador en su máquina de trabajo le basta con escribir un par de líneas en la configuración de Git o SSH. Para CI/CD, es necesario añadir variables de entorno en la configuración del runner o en la configuración del proyecto. Y para GitLab autoalojado, actualizar gitlab.rb y reconstruir la configuración.

Las principales reglas que ayudarán a evitar la mayoría de los problemas son:

• Usa SOCKS5 — funciona tanto con HTTPS como con SSH
• Siempre configura NO_PROXY para servicios internos
• No desactives la verificación SSL en producción — añade el certificado corporativo
• Para CI/CD, establece el proxy en config.toml, y no solo en .gitlab-ci.yml
• Documenta la configuración — un nuevo desarrollador en el equipo te lo agradecerá

Si estás buscando un proxy confiable para organizar un acceso estable a GitLab desde cualquier parte del mundo, te recomendamos considerar proxies de centros de datos — proporcionan alta velocidad de transferencia de datos y baja latencia, lo que es especialmente importante al trabajar con grandes repositorios y pipelines de CI/CD intensivos. Para equipos que valoran la máxima anonimidad o eludir bloqueos GeoIP, son adecuados proxies residenciales con IP de usuarios domésticos reales.