Configuração de proxy no GitHub Actions e CI/CD

A configuração de proxy no GitHub Actions e no CI/CD consiste em definir variáveis de ambiente de proxy padrão, como HTTP_PROXY, HTTPS_PROXY e NO_PROXY, dentro da definição do seu workflow, normalmente no nível do job ou do step. Isso permite que actions, scripts e ferramentas executados dentro do pipeline de CI/CD roteiem seu tráfego de rede através de um servidor proxy especificado.

As organizações costumam implantar servidores proxy para controlar o acesso de saída à rede, aplicar políticas de segurança, filtrar conteúdo e cachear recursos acessados com frequência. Para pipelines de CI/CD que operam nesses ambientes, configurar o proxy é essencial para que ferramentas de build, gerenciadores de dependências e scripts de teste consigam alcançar serviços externos, repositórios de pacotes ou APIs. Os runners do GitHub Actions, em especial os self-hosted, podem exigir configuração de proxy para acessar o próprio GitHub ou outros recursos da internet.

Definindo as variáveis de ambiente de proxy

O método mais comum e universalmente reconhecido para configurar um proxy em um ambiente baseado em Linux (que é o que os runners hospedados pelo GitHub usam principalmente) são as variáveis de ambiente.

• HTTP_PROXY: especifica o servidor proxy para requisições HTTP.
• HTTPS_PROXY: especifica o servidor proxy para requisições HTTPS.
• NO_PROXY: uma lista separada por vírgulas de hostnames, domínios ou endereços IP que devem ignorar o proxy. Isso é crítico para acessar recursos internos diretamente.

O formato de HTTP_PROXY e HTTPS_PROXY normalmente é http://[user:password@]host:port.
Tanto a versão em maiúsculas (HTTP_PROXY) quanto a em minúsculas (http_proxy) dessas variáveis costumam ser respeitadas por diversas ferramentas; usar maiúsculas é a prática padrão para variáveis de ambiente.

Configuração de proxy no nível do workflow

Aplicar as configurações de proxy no nível do job garante que todos os steps daquele job herdem a configuração.

name: CI with Proxy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com,github.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Node.js dependencies
        run: npm install

      - name: Download a file via curl
        run: curl -v https://api.example.com/data

      - name: Access internal service (bypasses proxy)
        run: curl -v http://internal-service.internal.company.com/status

Configuração de proxy no nível do step

Em cenários que exigem configurações de proxy diferentes para steps específicos, ou para sobrescrever as definições do job, as variáveis de ambiente podem ser definidas no nível do step.

name: CI with Specific Step Proxy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env: # Proxy padrão do job (se houver)
      HTTP_PROXY: http://default-proxy:8080
      HTTPS_PROXY: http://default-proxy:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Step using default proxy
        run: curl https://external-api.com/v1

      - name: Step using a different proxy
        env:
          HTTP_PROXY: http://special-proxy:3128
          HTTPS_PROXY: http://special-proxy:3128
          NO_PROXY: localhost,127.0.0.1,api.special-domain.com
        run: curl https://api.special-domain.com/v2

Autenticação de proxy com secrets

Se o seu proxy exigir autenticação, inclua o usuário e a senha diretamente na URL do proxy. Por segurança, armazene as credenciais como secrets do GitHub Actions e faça referência a elas no workflow.

Primeiro, crie os secrets do repositório (por exemplo, PROXY_USER, PROXY_PASS) nas configurações do seu repositório no GitHub.

name: Authenticated Proxy Workflow
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      HTTPS_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Perform network operation
        run: npm install # ou curl, etc.

Ferramentas comuns e a interação com o proxy

Embora HTTP_PROXY e HTTPS_PROXY sejam amplamente respeitados, algumas ferramentas oferecem métodos próprios de configuração.

Comandos git

O git geralmente respeita HTTP_PROXY e HTTPS_PROXY em operações remotas. Para uma configuração explícita ou nos casos em que as variáveis de ambiente não bastam, é possível usar git config.

# Define o proxy para operações git via HTTP e HTTPS
git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy http://proxy.example.com:8080

# Configura um proxy específico para um remote em particular
git config http.https://github.com/.proxy http://github-proxy:8080

npm, yarn

Gerenciadores de pacotes do Node.js como npm e yarn respeitam as variáveis de ambiente HTTP_PROXY e HTTPS_PROXY. Eles também oferecem seus próprios comandos de configuração para definições persistentes.

# Usando npm config
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080
npm config set no-proxy localhost,127.0.0.1,.internal.com

# Usando yarn config
yarn config set proxy http://proxy.example.com:8080
yarn config set httpsProxy http://proxy.example.com:8080
yarn config set no-proxy localhost,127.0.0.1,.internal.com

docker (build da imagem e runtime do contêiner)

As configurações de proxy no Docker exigem tratamento específico tanto no build da imagem quanto na execução do contêiner.

Proxy em tempo de build do Docker

Para comandos executados durante um docker build (por exemplo, RUN apk add, RUN apt-get update), as configurações de proxy devem ser passadas como build arguments.

Exemplo de Dockerfile:

FROM alpine:latest

# Define os build arguments das configurações de proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Define variáveis de ambiente para os comandos RUN seguintes
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

# Exemplo: usar o proxy para instalar pacotes
RUN apk add --no-cache curl

# ... o restante do seu Dockerfile

Step do workflow do GitHub Actions:

- name: Build Docker image with proxy
  run: |
    docker build . \
      --build-arg HTTP_PROXY=${{ env.HTTP_PROXY }} \
      --build-arg HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      --build-arg NO_PROXY=${{ env.NO_PROXY }} \
      -t my-app:latest

Proxy em tempo de execução do contêiner Docker

Se o seu workflow executa um contêiner Docker (por exemplo, usando a chave container: ou docker run), as configurações de proxy devem ser passadas como variáveis de ambiente para o contêiner.

Usando a chave container::

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: my-custom-image:latest
      env:
        HTTP_PROXY: ${{ env.HTTP_PROXY }}
        HTTPS_PROXY: ${{ env.HTTPS_PROXY }}
        NO_PROXY: ${{ env.NO_PROXY }}
    steps:
      - name: Run command inside container
        run: curl https://external-api.com/data

Usando docker run em um step:

- name: Run Docker container with proxy
  run: |
    docker run \
      -e HTTP_PROXY=${{ env.HTTP_PROXY }} \
      -e HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      -e NO_PROXY=${{ env.NO_PROXY }} \
      my-app:latest /app/script.sh

Aplicações Java (Maven, Gradle)

Aplicações Java, incluindo ferramentas de build como Maven e Gradle, normalmente exigem que as configurações de proxy sejam passadas como propriedades de sistema do Java. Isso costuma ser feito pelas variáveis de ambiente MAVEN_OPTS ou _JAVA_OPTIONS.

# Para o Maven
export MAVEN_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

# Para o Gradle (também vale para outras ferramentas baseadas em JVM)
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

Como alternativa, o Maven pode ser configurado via ~/.m2/settings.xml, e o Gradle via gradle.properties no projeto ou no diretório home do usuário.

Solução de problemas de proxy

• Verifique as variáveis de ambiente: use run: env | grep -i proxy em um step para confirmar que as variáveis de proxy estão corretamente definidas e visíveis para o shell do runner.
• Confira o NO_PROXY: garanta que quaisquer hosts internos ou domínios do GitHub estejam corretamente listados em NO_PROXY, para evitar proxying desnecessário ou problemas de roteamento.
• Logs do servidor proxy: se possível, verifique nos logs do servidor proxy as tentativas de conexão vindas do endereço IP do runner do GitHub Actions. Isso ajuda a determinar se a requisição está chegando ao proxy e por que ela pode estar sendo rejeitada (por exemplo, falha de autenticação, acesso negado).
• Conectividade de rede: use curl -v --proxy <your-proxy-url> <target-url> dentro de um step do workflow para testar explicitamente a conectividade através do proxy até um endpoint externo conhecido.
• Problemas de certificado SSL/TLS: se você usa um proxy HTTPS ou acessa sites HTTPS através de um proxy HTTP, e o proxy faz inspeção SSL, o runner pode encontrar erros de validação de certificado. Isso exige que o certificado da CA raiz do proxy seja adicionado ao trust store do runner. É uma configuração complexa, geralmente gerenciada em setups de runners self-hosted.

Resumo da configuração de proxy