Proxy per pipeline CI/CD: configurazione di GitHub Actions, GitLab CI e Jenkins per l'accesso a risorse private

Il tuo pipeline fallisce con l'errore 403 Forbidden o Connection refused quando cerchi di accedere a un'API esterna o scaricare una dipendenza? Probabilmente, il problema è che l'indirizzo IP del tuo server CI/CD è bloccato dal servizio. Il proxy risolve questo problema: instradi il traffico attraverso l'IP desiderato e il pipeline funziona senza interruzioni. In questo articolo troverai istruzioni passo passo per GitHub Actions, GitLab CI e Jenkins.

Perché usare un proxy in CI/CD: scenari reali

I pipeline CI/CD operano su server con indirizzi IP fissi — runner cloud di GitHub, GitLab o agenti Jenkins on-premise. Questi IP sono ben noti e molti servizi esterni li bloccano o limitano il numero di richieste. Ecco alcune situazioni specifiche in cui un proxy è indispensabile:

Accesso a risorse geo-limitate

Molti registri npm aziendali, repository Maven e API interne sono accessibili solo da determinati paesi o intervalli di IP. Se il tuo runner GitHub Actions si trova in una regione bloccata a livello di firewall dal servizio di destinazione, il pipeline non sarà in grado di scaricare dipendenze o inviare dati. Un proxy con la geolocalizzazione corretta risolve questo problema senza modificare l'infrastruttura.

Rate limiting e blocchi per IP

I runner cloud di GitHub Actions utilizzano IP da intervalli Microsoft Azure. Molti API pubblici conoscono questi intervalli e applicano limiti severi — o bloccano completamente. Ad esempio, il parsing di dati pubblici, le richieste a API esterne durante i test, il download di distribuzioni da CDN limitati — tutto ciò si interrompe regolarmente proprio a causa degli IP dei runner cloud. La rotazione tramite proxy consente di bypassare il rate limiting.

Test di integrazione con siti reali

Se i tuoi test di integrazione accedono a siti web o marketplace reali (Wildberries, Ozon, Avito, Amazon), questi siti vedono lo stesso IP dal runner ad ogni esecuzione e lo bloccano rapidamente. Un proxy con rotazione IP consente ai test di passare in modo stabile senza CAPTCHA e blocchi.

Accesso a risorse aziendali interne

Le reti aziendali sono spesso chiuse al mondo esterno. Se il pipeline deve effettuare il deploy su un server interno o accedere a un'API chiusa, un proxy (o un tunnel SOCKS5) all'interno della rete aziendale diventa un ponte tra il runner cloud e l'infrastruttura chiusa.

Test di integrazione pubblicitaria e marketing

I team che lavorano con le API di Facebook Ads, TikTok Ads o Google Ads automatizzano spesso la creazione di campagne tramite CI/CD. Queste piattaforme hanno regole rigide sugli IP: le richieste dagli IP dei data center possono essere bloccate o richiedere una verifica aggiuntiva. I proxy residenziali nel pipeline rendono le richieste simili al traffico normale degli utenti.

Quale tipo di proxy scegliere per il pipeline

La scelta del tipo di proxy dipende dal compito. Per i pipeline CI/CD, ci sono tre opzioni rilevanti — ognuna con i propri vantaggi e limitazioni:

Configurazione del proxy in GitHub Actions

GitHub Actions è lo strumento CI/CD più popolare al momento. La configurazione del proxy qui avviene tramite variabili d'ambiente e segreti del repository. Vediamo i passaggi.

Passo 1: Aggiungi i dati del proxy nei segreti del repository

Non inserire mai il nome utente e la password del proxy direttamente nel file YAML del workflow. Usa i segreti di GitHub:

1. Apri il repository → Impostazioni → Segreti e variabili → Actions
2. Fai clic su Nuovo segreto del repository
3. Crea un segreto PROXY_URL con un valore del tipo http://user:[email protected]:port

Passo 2: Usa le variabili d'ambiente nel workflow

La maggior parte degli strumenti (curl, wget, npm, pip, Maven) acquisisce automaticamente le variabili d'ambiente standard HTTP_PROXY, HTTPS_PROXY e NO_PROXY. Ecco un esempio di 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 in GitHub Actions

Se utilizzi SOCKS5 (raccomandato per la maggior parte dei compiti), le variabili d'ambiente standard non sono sufficienti — è necessario un tunnel locale. Usa l'utilità proxychains o configura 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

Configurazione del proxy per strumenti specifici

Alcuni strumenti ignorano le variabili di sistema e richiedono una configurazione separata:

Configurazione del proxy in GitLab CI

GitLab CI offre diversi livelli per impostare variabili d'ambiente: a livello di progetto, gruppo o istanza. Questo rende la gestione del proxy più flessibile rispetto a GitHub Actions.

Passo 1: Aggiungi variabili in GitLab CI/CD Variables

1. Apri il progetto → Impostazioni → CI/CD → sezione Variabili
2. Fai clic su Aggiungi variabile
3. Aggiungi la variabile PROXY_URL con tipo Masked (nasconde il valore nei log)
4. Valore: http://user:[email protected]:port

Passo 2: Usa le variabili in .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 solo per job specifici

Se il proxy non è necessario ovunque (ad esempio, solo per i test di integrazione, ma non per la build), imposta le variabili a livello di job specifico, non globalmente:

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

build:
  stage: build
  # Qui il proxy non è impostato — connessione diretta
  script:
    - npm ci && npm run build

GitLab Runner self-hosted: configurazione del proxy a livello di runner

Se utilizzi un GitLab Runner self-hosted, puoi impostare il proxy globalmente nella configurazione del runner. Apri il file /etc/gitlab-runner/config.toml e aggiungi nella sezione [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"
  ]

Questo è comodo quando tutti i pipeline su questo runner devono utilizzare il proxy — non è necessario specificarlo in ogni .gitlab-ci.yml.

Configurazione del proxy in Jenkins

Jenkins è lo strumento più flessibile dei tre, ma anche il più complesso da configurare. Qui il proxy può essere impostato a diversi livelli: globalmente per tutto Jenkins, per un Pipeline specifico o per un singolo passaggio.

Metodo 1: Impostazioni globali del proxy in Jenkins

1. Apri Gestisci Jenkins → System
2. Cerca la sezione Configurazione Proxy HTTP
3. Compila i campi: Server, Porta, Nome utente, Password
4. Nella sezione No Proxy Host specifica gli indirizzi interni separati da virgola
5. Fai clic su Test URL per verificare e salva

Questa impostazione influisce sul caricamento dei plugin e degli aggiornamenti di Jenkins stesso, ma non viene automaticamente trasferita nell'ambiente di esecuzione dei pipeline. Per i pipeline è necessaria una configurazione separata.

Metodo 2: Proxy nel Declarative Pipeline tramite 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: Aggiungi le credenziali del proxy in Jenkins Credentials

1. Apri Gestisci Jenkins → Credenziali → System → Credenziali globali
2. Fai clic su Aggiungi credenziali
3. Tipo: Testo segreto
4. ID: proxy-url-credential
5. Segreto: http://user:[email protected]:port

Metodo 3: Proxy tramite parametri JVM per progetti Java

Se il tuo pipeline costruisce un progetto Java (Maven, Gradle), le variabili d'ambiente di sistema potrebbero non funzionare — la JVM utilizza le proprie proprietà di sistema. Aggiungile a 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 all'interno dei contenitori Docker nel pipeline

La maggior parte dei moderni pipeline CI/CD esegue passaggi all'interno di contenitori Docker. Trasmettere il proxy nel contenitore è un compito separato che può essere risolto in diversi modi.

Trasmettere il proxy tramite --build-arg durante la costruzione dell'immagine

Se il proxy è necessario solo durante la costruzione dell'immagine Docker (ad esempio, per installare pacchetti all'interno del Dockerfile), utilizza gli argomenti di build:

# In .github/workflows/build.yml o .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 .

# In 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

Impostazione globale del daemon Docker per il proxy

Sui runner self-hosted, puoi configurare il proxy per l'intero daemon Docker — in questo modo, tutti i contenitori riceveranno automaticamente il proxy senza modifiche nel 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"

# Applica le modifiche:
# systemctl daemon-reload
# systemctl restart docker

Sicurezza: come gestire le credenziali del proxy

Le credenziali del proxy sono segreti proprio come le chiavi API o le password dei database. La loro fuga significa che chiunque può utilizzare il tuo proxy a tuo nome. Ecco le regole per una conservazione sicura:

Checklist di sicurezza

• ✅ Mai inserire il nome utente/password del proxy direttamente nei file YAML del pipeline
• ✅ Usa Variabili mascherate in GitLab e Segreti crittografati in GitHub — saranno nascosti nei log
• ✅ In Jenkins usa il tipo Testo segreto o Nome utente con password nel Credenziali Store
• ✅ Aggiungi NO_PROXY per indirizzi interni — il traffico verso la tua infrastruttura non deve passare attraverso il proxy
• ✅ Ruota regolarmente le password del proxy — aggiorna solo nel deposito dei segreti, senza modificare il codice del pipeline
• ✅ Usa l'autenticazione IP del proxy (whitelist IP del runner) dove supportata — è più sicura della password
• ✅ Controlla i log del proxy per attività insolite

Formato URL del proxy: cosa inserire dove

Errori comuni e come risolverli

Anche dopo una configurazione corretta, potrebbero sorgere problemi. Ecco gli errori più comuni e le loro soluzioni:

Errore: Proxy Authentication Required (407)

Errore: SSL Certificate Verification Failed

Errore: Connection Timeout attraverso il proxy

Errore: Lo strumento ignora le variabili HTTP_PROXY

Errore: I servizi interni passano anche attraverso il proxy

Conclusione

La configurazione del proxy nel pipeline CI/CD non è un compito una tantum, ma parte di una corretta architettura di automazione. Abbiamo esaminato tre strumenti principali: GitHub Actions (tramite Secrets e variabili d'ambiente), GitLab CI (tramite Variabili con mascheramento) e Jenkins (tramite Credenziali Store e Declarative Pipeline). I principi chiave sono gli stessi per tutti: non memorizzare mai le credenziali nel codice, utilizzare NO_PROXY per gli indirizzi interni e scegliere il tipo di proxy in base al compito specifico.

La scelta del tipo di proxy corretto è fondamentale per la stabilità del pipeline. Per scaricare dipendenze e accedere a API standard, sono sufficienti veloci proxy di data center. Se il tuo pipeline esegue test di integrazione su siti reali, lavora con piattaforme pubblicitarie (API di Facebook Ads, API di TikTok Ads) o accede a marketplace — utilizza proxy residenziali: i loro IP sono percepiti come traffico normale degli utenti e raramente vengono bloccati o soggetti a rate limiting.

La regola principale: testa il proxy in un passaggio separato all'inizio del pipeline — questo ti permetterà di diagnosticare rapidamente i problemi e di non perdere tempo a cercare errori alla fine di una lunga build. Aggiungi un passaggio curl -v https://api.ipify.org subito dopo la configurazione del proxy — mostrerà l'IP da cui partono le richieste e confermerà che il proxy funziona correttamente.