Proxies para GitLab: como configurar o acesso para a equipe e pipelines CI/CD sem falhas

```html

O GitLab é uma plataforma popular para armazenamento de código e gerenciamento de processos DevOps, utilizada por milhares de equipes em todo o mundo. Mas o que fazer se o acesso ao GitLab estiver bloqueado pelo provedor, pela rede corporativa ou por um país inteiro? E pior ainda — quando o pipeline CI/CD falha no meio da noite simplesmente porque o runner não consegue acessar o repositório.

Neste artigo, vamos discutir como configurar um proxy para o GitLab no nível do cliente Git, do GitLab Runner e do servidor corporativo — para que toda a equipe trabalhe de forma estável de qualquer lugar do mundo.

Por que um proxy é necessário para o GitLab: cenários reais

Antes de configurar um proxy, é importante entender qual problema específico você está resolvendo. As situações podem variar, e isso afeta a escolha do tipo de proxy e a forma como ele é conectado.

Cenário 1: GitLab bloqueado pelo provedor ou em nível nacional

Em vários países e redes corporativas, o acesso ao gitlab.com é restrito. O desenvolvedor abre o terminal, digita git pull — e recebe um timeout. O proxy, nesse caso, atua como intermediário: o tráfego não vai diretamente para gitlab.com, mas através de um servidor intermediário em um país onde não há restrições.

Cenário 2: Equipe distribuída em diferentes países

Imagine: parte da equipe trabalha da Rússia, parte do Cazaquistão, parte da Europa. Cada um tem condições de rede diferentes, diferentes restrições. Para que todos trabalhem de forma estável e com a mesma velocidade, as empresas implementam um servidor proxy corporativo, pelo qual todo o tráfego para o GitLab passa por um único canal.

Cenário 3: CI/CD runner não consegue acessar dependências externas

O GitLab Runner inicia um pipeline, e na etapa npm install ou pip install tudo falha — porque o servidor onde o runner está localizado está em uma rede fechada sem acesso direto à internet. O proxy permite que o runner obtenha dependências externas, sem abrir acesso total à internet para todo o servidor.

Cenário 4: GitLab self-hosted atrás de um firewall corporativo

A empresa mantém seu próprio servidor GitLab em uma rede interna. Desenvolvedores remotos precisam se conectar a ele. Em vez de usar VPN para todo o tráfego, é possível configurar um proxy apenas para o tráfego do GitLab — isso é mais rápido e mais fácil de administrar.

Cenário 5: Monitoramento e auditoria de tráfego

Grandes empresas direcionam todo o tráfego para os repositórios através de um proxy corporativo, para registrar a atividade, controlar quem e o que está fazendo push, e bloquear operações indesejadas. Isso é uma exigência de segurança, e não apenas uma forma de contornar bloqueios.

Importante entender antes da configuração:

Um proxy para o GitLab pode ser necessário em três níveis simultaneamente: na máquina do desenvolvedor (cliente Git), no servidor com o GitLab Runner (CI/CD), e no próprio servidor GitLab (se for self-hosted). Cada nível é configurado separadamente.

Qual tipo de proxy é adequado para o GitLab

O GitLab opera nos protocolos HTTPS e SSH. Isso imediatamente determina quais tipos de proxy são aplicáveis e quais não são. Vamos analisar as opções.

Tipo de proxy	Protocolo	Adequado para GitLab	Quando usar
Proxy HTTP/HTTPS	HTTP, HTTPS	✓ Sim	Git over HTTPS, interface web do GitLab
Proxy SOCKS5	TCP (qualquer)	✓ Sim (melhor opção)	Git over HTTPS e SSH, CI/CD
Proxy SOCKS4	TCP	~ Parcialmente	Apenas se SOCKS5 não estiver disponível
Proxy transparente	HTTP	✗ Não	Não é adequado — não contorna bloqueios

Para trabalhar com o GitLab, a escolha ideal é SOCKS5. Ele opera no nível TCP, portanto, proxy tanto as conexões HTTPS (interface web, git clone via HTTPS) quanto as conexões SSH (git push/pull via SSH na porta 22 ou 443) de forma igualmente eficaz.

Proxies residenciais vs de datacenter para GitLab

Aqui tudo depende da tarefa. Se o objetivo é contornar bloqueios por GeoIP ou obter um IP estável para autenticação, proxies de datacenter são adequados — eles são mais rápidos, mais baratos e oferecem baixa latência, o que é crítico ao trabalhar com grandes repositórios.

No entanto, se o seu IP corporativo foi listado em uma blacklist do GitLab (o que pode ocorrer devido a varreduras agressivas ou após incidentes de segurança), então vale a pena considerar proxies residenciais — seus endereços IP pertencem a usuários domésticos reais e raramente são bloqueados pelas plataformas.

Configuração de proxy para o cliente Git (globalmente)

Este é o cenário mais comum: o desenvolvedor em sua máquina não consegue se conectar ao GitLab. A configuração é feita através da configuração do próprio Git — uma vez, e funciona para todos os repositórios.

Opção A: Proxy HTTPS para Git

Se você está trabalhando com o GitLab via HTTPS (o endereço do repositório começa com https://), execute no terminal:

# Configurar proxy HTTP globalmente
git config --global http.proxy http://SEU_PROXY_IP:PORTA

# Se o proxy exigir autenticação
git config --global http.proxy http://LOGIN:SENHA@SEU_PROXY_IP:PORTA

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

# Verificar se a configuração foi aplicada
git config --global --get http.proxy

Opção B: Proxy apenas para gitlab.com (não afeta outros repositórios)

Se você não deseja que o proxy seja aplicado a todas as operações do Git (por exemplo, GitHub ou Bitbucket funcionam normalmente), você pode configurar o proxy apenas para um domínio específico:

# Proxy apenas para gitlab.com
git config --global http.https://gitlab.com.proxy socks5://SEU_PROXY_IP:PORTA

# Ou para o seu GitLab self-hosted
git config --global http.https://git.seuempresa.com.proxy socks5://SEU_PROXY_IP:PORTA

Opção C: SSH através de proxy (para quem trabalha via SSH)

Se você está clonando repositórios via SSH ([email protected]:...), a configuração do proxy é feita no arquivo de configuração SSH, e não no Git. Abra o arquivo ~/.ssh/config e adicione:

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

# Para Windows — através de connect.exe (Git for Windows)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand connect -S SEU_PROXY_IP:PORTA %h %p

Após a configuração, verifique a conexão com o comando ssh -T [email protected]. Se tudo estiver configurado corretamente, você verá uma mensagem de boas-vindas do GitLab.

Como desativar o proxy quando não for mais necessário

# Remover proxy global
git config --global --unset http.proxy

# Remover proxy para um domínio específico
git config --global --unset http.https://gitlab.com.proxy

Proxy para GitLab Runner e pipelines CI/CD

O GitLab Runner é um agente que executa tarefas do .gitlab-ci.yml. Se o runner estiver em uma rede fechada ou em um servidor com acesso à internet limitado, é necessário configurar o proxy separadamente. As configurações do cliente Git do desenvolvedor não ajudarão aqui — o runner opera em outra máquina.

Método 1: Variáveis de ambiente na configuração do runner

Abra o arquivo de configuração do GitLab Runner (geralmente /etc/gitlab-runner/config.toml) e adicione variáveis de ambiente na seção [runners.env]:

[[runners]]
  name = "meu-runner"
  url = "https://gitlab.com/"
  token = "SEU_TOKEN"
  executor = "shell"
  environment = [
    "HTTP_PROXY=http://SEU_PROXY_IP:PORTA",
    "HTTPS_PROXY=http://SEU_PROXY_IP:PORTA",
    "NO_PROXY=localhost,127.0.0.1,seu-dominio-interno.com"
  ]

Após alterar a configuração, reinicie o runner: sudo gitlab-runner restart

Método 2: Variáveis no .gitlab-ci.yml (no nível do pipeline)

Se você não é o administrador do runner ou deseja configurar o proxy apenas para um projeto específico, adicione as variáveis diretamente no arquivo do pipeline:

variables:
  HTTP_PROXY: "http://SEU_PROXY_IP:PORTA"
  HTTPS_PROXY: "http://SEU_PROXY_IP:PORTA"
  NO_PROXY: "localhost,127.0.0.1,.empresa.interna.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - npm install   # agora irá passar pelo proxy
    - npm run build

Método 3: Variáveis nas configurações do projeto GitLab (sem commit no repositório)

A melhor forma para dados sensíveis (proxy com autenticação): vá para Configurações → CI/CD → Variáveis do seu projeto e adicione as variáveis HTTP_PROXY, HTTPS_PROXY, NO_PROXY como variáveis protegidas (masked). Elas estarão automaticamente disponíveis em todos os pipelines, mas não serão visíveis nos logs.

Proxy para executor Docker

Se o runner utiliza o executor Docker, os contêineres por padrão não herdam as configurações de proxy do host. É necessário adicionar as variáveis na config.toml na seção [runners.docker], ou criar um arquivo /etc/systemd/system/docker.service.d/proxy.conf no host com o runner:

[Service]
Environment="HTTP_PROXY=http://SEU_PROXY_IP:PORTA"
Environment="HTTPS_PROXY=http://SEU_PROXY_IP:PORTA"
Environment="NO_PROXY=localhost,127.0.0.1"

Após isso: sudo systemctl daemon-reload && sudo systemctl restart docker

Proxy para servidor GitLab self-hosted

Se você administra seu próprio servidor GitLab (instalado via Omnibus ou Helm), o proxy é necessário para que o próprio GitLab possa acessar serviços externos: enviar notificações, conectar-se a sistemas CI externos, carregar avatares de usuários, integrar-se com Jira ou Slack.

Configuração no gitlab.rb (instalação Omnibus)

Abra o arquivo /etc/gitlab/gitlab.rb e adicione ou descomente as seguintes linhas:

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

# Se o proxy exigir autenticação:
gitlab_rails['env'] = {
  "http_proxy" => "http://LOGIN:SENHA@SEU_PROXY_IP:PORTA",
  "https_proxy" => "http://LOGIN:SENHA@SEU_PROXY_IP:PORTA",
  "no_proxy" => "localhost,127.0.0.1"
}

Após alterar a configuração, aplique as configurações: sudo gitlab-ctl reconfigure

Configuração de conexões de saída através da Área de Administração

No GitLab 15.0+, há a possibilidade de configurar o proxy diretamente através da interface web: vá para Área de Administração → Configurações → Rede → Solicitações de saída. Aqui você pode especificar um proxy para webhooks de saída e restringir os intervalos de IPs aos quais o GitLab pode se conectar. Isso é útil para segurança — previne ataques SSRF através de webhooks.

Organização de acesso para toda a equipe através de proxy

Quando é necessário garantir acesso estável ao GitLab para uma equipe de 5 a 50 pessoas, a configuração individual em cada máquina não é a melhor abordagem. Vamos considerar soluções mais escaláveis.

Abordagem 1: Servidor proxy corporativo

Um servidor proxy (por exemplo, Squid ou 3proxy) é implementado com acesso à internet. Todos os desenvolvedores configuram o Git para usar esse servidor. Vantagens: gerenciamento centralizado, ponto único de controle, é possível registrar o tráfego. Desvantagem: o servidor se torna um único ponto de falha.

Abordagem 2: Espelho (mirror) do repositório

O GitLab suporta espelhamento de repositórios. É possível configurar um GitLab self-hosted na rede interna como um espelho do gitlab.com. Os desenvolvedores trabalham com o servidor interno, que se sincroniza com o externo através do proxy. Isso reduz a dependência da qualidade da conexão proxy para cada desenvolvedor.

Abordagem 3: Configuração automática através de dotfiles ou script de onboarding

Para equipes onde cada desenvolvedor configura seu ambiente, é conveniente criar um script de onboarding que automaticamente escreve as configurações necessárias do Git. O script é armazenado em um repositório corporativo e é executado ao configurar um novo local de trabalho.

#!/bin/bash
# setup-git-proxy.sh — executar ao configurar um novo local de trabalho

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

echo "Configurando proxy Git para acesso ao GitLab..."
git config --global http.https://gitlab.com.proxy "socks5://${PROXY_HOST}:${PROXY_PORT}"
git config --global http.sslVerify true
echo "Pronto! Verifique: git config --global --list | grep proxy"

Checklist para implantação em equipe

• Determinar se o proxy é necessário no nível dos desenvolvedores, runners ou servidor GitLab (ou todos os três)
• Escolher o tipo de proxy: SOCKS5 para máxima compatibilidade
• Configurar NO_PROXY para todos os domínios e serviços internos
• Verificar o funcionamento das chaves SSH através do proxy (passo separado!)
• Documentar as configurações na wiki corporativa
• Criar um script de onboarding para novos funcionários
• Configurar monitoramento da disponibilidade do servidor proxy

Problemas comuns e suas soluções

Mesmo após a configuração correta, às vezes algo não funciona como deveria. Aqui estão os problemas mais comuns e como diagnosticá-los.

Problema 1: Problema com certificado SSL: não é possível obter o certificado do emissor local

Este erro ocorre quando o servidor proxy (especialmente o corporativo) realiza inspeção SSL — substituindo o certificado do GitLab pelo seu. O Git não confia nesse certificado. Solução: adicione o certificado raiz corporativo aos confiáveis.

# Solução temporária (para depuração, não para produção!)
git config --global http.sslVerify false

# Solução correta: adicionar o certificado corporativo
git config --global http.sslCAInfo /caminho/para/corporate-ca-bundle.crt

Problema 2: Proxy funciona para HTTPS, mas SSH não

Esta é uma situação clássica: você configurou http.proxy no Git, a clonagem via HTTPS funcionou, mas as operações SSH ainda não passam. A razão: o tráfego SSH não passa pelo proxy HTTP. É necessário configurar separadamente ~/.ssh/config como descrito na seção sobre o cliente Git.

Alternativa: mudar para trabalhar com o GitLab via HTTPS em vez de SSH. Para isso, altere a URL remota:

# Verificar o remote atual
git remote -v

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

Problema 3: Pipeline CI/CD trava na etapa de clonagem do repositório

O runner clona o repositório diretamente do GitLab, usando um token. Se o runner estiver atrás de um proxy, essa clonagem também deve passar pelo proxy. Certifique-se de que as variáveis HTTP_PROXY e HTTPS_PROXY estão configuradas no config.toml, e não apenas no .gitlab-ci.yml — as variáveis do arquivo CI são aplicadas após a clonagem, e não antes.

Problema 4: Proxy funciona, mas muito lentamente

Se push/pull funcionam, mas levam 5 a 10 vezes mais tempo do que o normal, o problema pode estar na largura de banda do servidor proxy ou em sua localização geográfica. Para trabalhar com grandes repositórios (100+ MB), é importante escolher um proxy com baixa latência e alta largura de banda. Proxies de datacenter são preferíveis a residenciais nesse caso — eles oferecem um canal mais estável.

Problema 5: Autenticação através do proxy requer reentrada de senha

Se o proxy exigir autenticação básica, e o Git solicitar a senha a cada vez, configure o helper de credenciais:

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

# Windows — usar Gerenciador de Credenciais do Windows
git config --global credential.helper manager

# Linux — armazenar em cache por 1 hora
git config --global credential.helper "cache --timeout=3600"

Conclusão e recomendações

A configuração do proxy para o GitLab é uma tarefa que deve ser resolvida em vários níveis simultaneamente. Para o desenvolvedor em sua máquina de trabalho, é suficiente adicionar algumas linhas na configuração do Git ou SSH. Para CI/CD, é necessário adicionar variáveis de ambiente na configuração do runner ou nas configurações do projeto. E para o GitLab self-hosted — atualizar o gitlab.rb e reconfigurar.

As principais regras que ajudarão a evitar a maioria dos problemas:

• Use SOCKS5 — ele funciona tanto com HTTPS quanto com SSH
• Sempre configure NO_PROXY para serviços internos
• Não desative a verificação SSL em produção — adicione o certificado corporativo
• Para CI/CD, configure o proxy em config.toml, e não apenas em .gitlab-ci.yml
• Documente as configurações — um novo desenvolvedor na equipe agradecerá

Se você está procurando um proxy confiável para garantir acesso estável ao GitLab de qualquer lugar do mundo, recomendamos considerar proxies de datacenter — eles oferecem alta velocidade de transferência e baixa latência, o que é especialmente importante ao trabalhar com grandes repositórios e pipelines CI/CD intensivos. Para equipes que valorizam a máxima anonimidade ou a contorna de bloqueios GeoIP, proxies residenciais com IPs de usuários domésticos reais são uma boa opção.