← Voltar ao blog
RUENZHESARPTDEFRJAKOITTRIDVIFAHI

Proxies para Pipelines CI/CD: Configuração do GitHub Actions, GitLab CI e Jenkins para Acesso a Recursos Privados

Guia completo para configurar o proxy em pipelines CI/CD: GitHub Actions, GitLab CI e Jenkins. Como contornar geo-bloqueios, acessar APIs restritas e acelerar a construção através de proxy.

📅16 de maio de 2026
```html

Seu pipeline falha com o erro 403 Forbidden ou Connection refused ao tentar acessar uma API externa ou baixar uma dependência? Provavelmente, o problema é que o endereço IP do seu servidor CI/CD está bloqueado do lado do recurso. O proxy resolve esse problema: você roteia o tráfego através do IP necessário e o pipeline funciona sem falhas. Neste artigo, você encontrará instruções passo a passo para GitHub Actions, GitLab CI e Jenkins.

Por que usar um proxy em CI/CD: cenários reais

Os pipelines de CI/CD operam em servidores com endereços IP fixos — runners em nuvem do GitHub, GitLab ou em seus próprios agentes do Jenkins. Esses IPs são bem conhecidos, e muitos serviços externos bloqueiam ou limitam o número de solicitações. Aqui estão situações específicas em que um proxy é indispensável:

Acesso a recursos geograficamente restritos

Muitos repositórios npm corporativos, repositórios Maven e APIs internas estão disponíveis apenas a partir de determinados países ou faixas de IP. Se seu runner do GitHub Actions estiver em uma região bloqueada pelo firewall do serviço de destino, o pipeline não conseguirá baixar dependências ou enviar dados. Um proxy com a geolocalização necessária resolve essa tarefa sem alterar a infraestrutura.

Limitação de taxa e bloqueios por IP

Os runners em nuvem do GitHub Actions usam IPs de faixas da Microsoft Azure. Muitas APIs públicas conhecem essas faixas e aplicam limites rigorosos — ou bloqueiam completamente. Por exemplo, a extração de dados públicos, solicitações a APIs externas durante testes, downloads de distribuições de CDNs restritos — tudo isso frequentemente falha devido aos IPs dos runners em nuvem. A rotação através de um proxy permite contornar a limitação de taxa.

Testes de integração com sites reais

Se seus testes de integração acessam sites reais ou marketplaces (Wildberries, Ozon, Avito, Amazon), esses sites veem o mesmo IP do runner a cada execução e rapidamente o bloqueiam. Um proxy com rotação de IP permite que os testes sejam executados de forma estável, sem CAPTCHAs e bloqueios.

Acesso a recursos corporativos internos

Redes corporativas frequentemente estão fechadas para o mundo externo. Se o pipeline precisa implantar em um servidor interno ou acessar uma API fechada, um proxy (ou túnel SOCKS5) dentro da rede corporativa se torna uma ponte entre o runner em nuvem e a infraestrutura fechada.

Testes de integrações publicitárias e de marketing

Equipes que trabalham com a API do Facebook Ads, API do TikTok Ads ou API do Google Ads frequentemente automatizam a criação de campanhas através de CI/CD. Essas plataformas têm regras rigorosas sobre IP: solicitações de IPs de data centers podem ser bloqueadas ou exigir verificação adicional. Proxies residenciais no pipeline tornam as solicitações semelhantes ao tráfego de usuários comuns.

Qual tipo de proxy escolher para o pipeline

A escolha do tipo de proxy depende da tarefa. Para pipelines de CI/CD, três opções são relevantes — cada uma com seus prós e contras:

Tipo de proxy Velocidade Confiança dos sites Melhor para
Proxies de data center Muito alta Média Baixar dependências, repositórios internos, APIs rápidas sem verificações rigorosas
Proxies residenciais Média Alta Testes de integração com sites reais, APIs publicitárias (Facebook, TikTok), marketplaces
Proxies móveis Média Máxima Testes de APIs móveis, trabalho com plataformas com proteções anti-bot máximas

Regra prática:

Se a tarefa é baixar pacotes ou acessar um serviço interno, use proxies de data center — eles são rápidos e mais baratos. Se a tarefa é realizar testes em sites reais ou trabalhar com plataformas publicitárias — use proxies residenciais. O protocolo SOCKS5 é preferível ao HTTP/HTTPS, pois funciona de forma mais transparente com portas e protocolos não padrão.

Configurando o proxy no GitHub Actions

O GitHub Actions é a ferramenta de CI/CD mais popular atualmente. A configuração do proxy aqui é feita através de variáveis de ambiente e segredos do repositório. Vamos detalhar passo a passo.

Passo 1: Adicione os dados do proxy aos segredos do repositório

Nunca insira o login e a senha do proxy diretamente no arquivo YAML do workflow. Use os Segredos do GitHub:

  1. Abra o repositório → Settings → Secrets and variables → Actions
  2. Clique em New repository secret
  3. Crie um segredo PROXY_URL com o valor no formato http://user:[email protected]:port

Passo 2: Use variáveis de ambiente no workflow

A maioria das ferramentas (curl, wget, npm, pip, Maven) automaticamente reconhece as variáveis de ambiente padrão HTTP_PROXY, HTTPS_PROXY e NO_PROXY. Exemplo de workflow: 

name: Build with Proxy

on: [push]

env:
  HTTP_PROXY: ${{ secrets.PROXY_URL }}
  HTTPS_PROXY: ${{ secrets.PROXY_URL }}
  NO_PROXY: localhost,127.0.0.1,internal.company.com

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm ci

      - name: Run integration tests
        run: npm test

      - name: Call external API
        run: |
          curl -v https://api.example.com/data

Passo 3: Proxy SOCKS5 no GitHub Actions

Se você estiver usando SOCKS5 (recomendado para a maioria das tarefas), as variáveis de ambiente padrão não são suficientes — é necessário um túnel local. Use a ferramenta proxychains ou configure microsocks: 

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Setup SOCKS5 proxy tunnel
        run: |
          sudo apt-get install -y proxychains4
          echo "socks5 proxy.host 1080 user password" >> /etc/proxychains4.conf

      - name: Run command through SOCKS5
        run: proxychains4 curl https://restricted-resource.com/api

Configurando o proxy para ferramentas específicas

Algumas ferramentas ignoram as variáveis do sistema e requerem configuração separada:

Ferramenta Como configurar o proxy
npm / yarn npm config set proxy http://user:pass@host:port
pip (Python) pip install --proxy http://user:pass@host:port package
Maven Através do settings.xml seção <proxies>
Gradle systemProp.https.proxyHost=host em gradle.properties
Git git config --global http.proxy http://user:pass@host:port
Docker build --build-arg HTTP_PROXY=http://user:pass@host:port

Configurando o proxy no GitLab CI

O GitLab CI oferece vários níveis para definir variáveis de ambiente: no nível do projeto, grupo ou instância. Isso torna o gerenciamento de proxies mais flexível em comparação com o GitHub Actions.

Passo 1: Adicione variáveis em GitLab CI/CD Variables

  1. Abra o projeto → Settings → CI/CD → seção Variables
  2. Clique em Add variable
  3. Adicione a variável PROXY_URL com o tipo Masked (oculta o valor nos logs)
  4. Valor: http://user:[email protected]:port

Passo 2: Use variáveis no .gitlab-ci.yml

variables:
  HTTP_PROXY: $PROXY_URL
  HTTPS_PROXY: $PROXY_URL
  NO_PROXY: "localhost,127.0.0.1,.internal.company.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  image: node:20-alpine
  script:
    - npm ci
    - npm run build

integration_tests:
  stage: test
  image: python:3.11
  script:
    - pip install -r requirements.txt
    - pytest tests/integration/

deploy:
  stage: deploy
  script:
    - curl -X POST https://api.external-service.com/deploy
      -H "Authorization: Bearer $DEPLOY_TOKEN"
      -d '{"version": "$CI_COMMIT_SHA"}'

Proxy apenas para jobs específicos

Se o proxy não for necessário em todos os lugares (por exemplo, apenas para testes de integração, mas não para a construção), defina as variáveis no nível de um job específico, e não globalmente: 

integration_tests:
  stage: test
  variables:
    HTTP_PROXY: $PROXY_URL
    HTTPS_PROXY: $PROXY_URL
  script:
    - pytest tests/integration/

build:
  stage: build
  # Aqui o proxy não está definido — conexão direta
  script:
    - npm ci && npm run build

GitLab Runner auto-hospedado: configurando o proxy no nível do runner

Se você estiver usando seu próprio GitLab Runner, pode definir o proxy globalmente na configuração do runner. Abra o arquivo /etc/gitlab-runner/config.toml e adicione na seção [runners.env]: 

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "TOKEN"
  executor = "docker"
  environment = [
    "HTTP_PROXY=http://user:[email protected]:port",
    "HTTPS_PROXY=http://user:[email protected]:port",
    "NO_PROXY=localhost,127.0.0.1"
  ]

Isso é conveniente quando todos os pipelines nesse runner devem usar o proxy — não é necessário especificá-lo em cada .gitlab-ci.yml.

Configurando o proxy no Jenkins

O Jenkins é o mais flexível dos três ferramentas, mas também o mais complexo de configurar. O proxy pode ser definido em vários níveis: globalmente para todo o Jenkins, para um Pipeline específico ou para um passo individual.

Método 1: Configurações globais de proxy no Jenkins

  1. Abra Manage Jenkins → System
  2. Encontre a seção HTTP Proxy Configuration
  3. Preencha os campos: Server, Port, Username, Password
  4. No campo No Proxy Host, especifique os endereços internos separados por vírgula
  5. Clique em Test URL para verificar e salve

Essa configuração afeta o download de plugins e atualizações do próprio Jenkins, mas não é automaticamente transmitida para o ambiente de execução dos pipelines. Para os pipelines, uma configuração separada é necessária.

Método 2: Proxy no Pipeline Declarativo através de environment

pipeline {
    agent any

    environment {
        HTTP_PROXY  = credentials('proxy-url-credential')
        HTTPS_PROXY = credentials('proxy-url-credential')
        NO_PROXY    = 'localhost,127.0.0.1,internal.company.com'
    }

    stages {
        stage('Build') {
            steps {
                sh 'npm ci'
                sh 'npm run build'
            }
        }

        stage('Integration Tests') {
            steps {
                sh 'pytest tests/integration/'
            }
        }

        stage('Deploy') {
            steps {
                sh '''
                    curl -X POST https://api.external-service.com/deploy \
                    -H "Authorization: Bearer ${DEPLOY_TOKEN}" \
                    -d "version=${GIT_COMMIT}"
                '''
            }
        }
    }
}

Passo 3: Adicione as credenciais do proxy nas Credenciais do Jenkins

  1. Abra Manage Jenkins → Credentials → System → Global credentials
  2. Clique em Add Credentials
  3. Tipo: Secret text
  4. ID: proxy-url-credential
  5. Secret: http://user:[email protected]:port

Método 3: Proxy através de parâmetros JVM para projetos Java

Se seu pipeline constrói um projeto Java (Maven, Gradle), as variáveis de ambiente do sistema podem não funcionar — a JVM usa suas próprias propriedades do sistema. Adicione-as em JAVA_OPTS: 

environment {
    JAVA_OPTS = '-Dhttps.proxyHost=proxy.host -Dhttps.proxyPort=8080 -Dhttps.proxyUser=user -Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.internal.com'
}

Proxy dentro de contêineres Docker no pipeline

A maioria dos pipelines modernos de CI/CD executa etapas dentro de contêineres Docker. Passar o proxy para o contêiner é uma tarefa separada que pode ser resolvida de várias maneiras.

Passando o proxy através de --build-arg ao construir a imagem

Se o proxy for necessário apenas durante a construção da imagem Docker (por exemplo, para instalar pacotes dentro do Dockerfile), use argumentos de construção: 

# Em .github/workflows/build.yml ou .gitlab-ci.yml
docker build \
  --build-arg HTTP_PROXY=$HTTP_PROXY \
  --build-arg HTTPS_PROXY=$HTTPS_PROXY \
  --build-arg NO_PROXY=$NO_PROXY \
  -t myapp:latest .

# No Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

RUN apt-get update && apt-get install -y curl
RUN npm ci

⚠️ Importante: segurança ao construir imagens

Variáveis definidas através de ARG e ENV no Dockerfile são armazenadas nos metadados da imagem e visíveis através de docker inspect. Se o proxy exigir autenticação, certifique-se de que a imagem final não seja publicada em um registro público — caso contrário, as credenciais estarão acessíveis publicamente.

Configuração global do daemon Docker para proxy

Em runners auto-hospedados, é possível configurar o proxy para todo o daemon Docker — assim, todos os contêineres receberão automaticamente o proxy sem alterações no Dockerfile: 

# /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://user:[email protected]:port"
Environment="HTTPS_PROXY=http://user:[email protected]:port"
Environment="NO_PROXY=localhost,127.0.0.1,registry.internal.com"

# Aplicar as alterações:
# systemctl daemon-reload
# systemctl restart docker

Segurança: como armazenar credenciais do proxy

As credenciais do proxy são segredos como chaves de API ou senhas de bancos de dados. A sua exposição significa que qualquer um pode usar seu proxy às suas custas. Aqui estão as regras para armazenamento seguro:

Checklist de segurança

  • ✅ Nunca insira login/senha do proxy diretamente em arquivos YAML do pipeline
  • ✅ Use Masked variables no GitLab e Encrypted secrets no GitHub — eles são ocultados nos logs
  • ✅ No Jenkins, use o tipo Secret text ou Username with password no Credentials Store
  • ✅ Adicione NO_PROXY para endereços internos — o tráfego para sua infraestrutura não deve passar pelo proxy
  • ✅ Rode regularmente as senhas do proxy — atualize apenas no armazenamento de segredos, sem alterar o código do pipeline
  • ✅ Use autenticação IP do proxy (whitelist do IP do runner) onde suportado — isso é mais seguro que uma senha
  • ✅ Verifique os logs do proxy em busca de atividades incomuns

Formato de URL do proxy: o que inserir onde

Protocolo Formato da URL Quando usar
HTTP http://user:pass@host:port A maioria das ferramentas, npm, pip, curl
HTTPS https://user:pass@host:port Conexão criptografada com o servidor proxy
SOCKS5 socks5://user:pass@host:port Portas não padrão, tráfego UDP, máxima compatibilidade

Erros comuns e como corrigi-los

Mesmo após a configuração correta, podem surgir problemas. Aqui estão os erros mais comuns e suas soluções:

Erro: Proxy Authentication Required (407)

Razão: Login ou senha incorretos, ou eles não estão sendo transmitidos pela ferramenta.

Solução: Verifique o formato da URL — caracteres especiais na senha precisam ser codificados em URL. Por exemplo, p@ss#word → p%40ss%23word. Além disso, certifique-se de que a variável de ambiente está realmente sendo passada para o passo — imprima-a usando echo $HTTP_PROXY (os primeiros caracteres) para verificação.

Erro: SSL Certificate Verification Failed

Razão: O proxy está realizando inspeção SSL (MITM) e substituindo o certificado. O cliente não confia no certificado do proxy.

Solução: Adicione o certificado raiz do proxy aos confiáveis. Para curl: --cacert /path/to/proxy-ca.crt. Para npm: npm config set cafile /path/to/proxy-ca.crt. Ou use um proxy sem inspeção SSL — isso é preferível para CI/CD.

Erro: Connection Timeout através do proxy

Razão: O servidor proxy não está acessível a partir do IP do runner, ou a porta está bloqueada pelo firewall.

Solução: Verifique a acessibilidade do proxy com o comando nc -zv proxy.host port em um passo do pipeline. Certifique-se de que o IP do runner está na lista de permissões do provedor de proxy (se a autenticação por IP estiver em uso). Para runners em nuvem do GitHub Actions, os intervalos de IP são publicados em meta.github.com.

Erro: A ferramenta ignora as variáveis HTTP_PROXY

Razão: Algumas ferramentas (especialmente as baseadas em Java) não leem as variáveis de ambiente do sistema.

Solução: Use a configuração nativa do proxy para a ferramenta específica (veja a tabela acima). Para Java, adicione propriedades JVM através de JAVA_OPTS. Para curl, use a flag -x http://proxy:port explicitamente.

Erro: Serviços internos também estão passando pelo proxy

Razão: A variável NO_PROXY não está definida ou está definida incorretamente.

Solução: Especifique todos os domínios internos e IPs em NO_PROXY. Use wildcards para domínios: NO_PROXY=localhost,127.0.0.1,10.0.0.0/8,.internal.company.com. Observe que algumas ferramentas suportam notação CIDR, enquanto outras aceitam apenas domínios exatos.

Conclusão

Configurar um proxy em um pipeline de CI/CD não é uma tarefa única, mas parte de uma arquitetura de automação adequada. Discutimos três ferramentas principais: GitHub Actions (através de Secrets e variáveis de ambiente), GitLab CI (através de Variables com mascaramento) e Jenkins (através de Credentials Store e Declarative Pipeline). Os princípios-chave são os mesmos para todos: nunca armazenar credenciais no código, usar NO_PROXY para endereços internos e escolher o tipo de proxy para a tarefa específica.

A escolha do tipo de proxy correto é crítica para a estabilidade do pipeline. Para baixar dependências e acessar APIs padrão, proxies de data center rápidos são suficientes. No entanto, se seu pipeline realiza testes de integração em sites reais, trabalha com plataformas publicitárias (API do Facebook Ads, API do TikTok Ads) ou acessa marketplaces — use proxies residenciais: seus IPs são percebidos como tráfego de usuários comuns e raramente são bloqueados ou limitados.

A regra principal: teste o proxy em um passo separado no início do pipeline — isso permitirá diagnosticar problemas rapidamente e evitar perder tempo procurando erros no final de uma longa construção. Adicione um passo curl -v https://api.ipify.org logo após a configuração do proxy — isso mostrará o IP de onde as solicitações estão saindo e confirmará que o proxy está funcionando corretamente.

```