Proxys für CI/CD-Pipelines: Einrichtung von GitHub Actions, GitLab CI und Jenkins für den Zugriff auf geschützte Ressourcen

Fällt Ihre Pipeline mit einem Fehler 403 Forbidden oder Connection refused aus, wenn Sie versuchen, auf eine externe API zuzugreifen oder eine Abhängigkeit herunterzuladen? Höchstwahrscheinlich liegt das daran, dass die IP-Adresse Ihres CI/CD-Servers auf der Seite der Ressource blockiert ist. Ein Proxy löst dieses Problem: Sie leiten den Verkehr über die benötigte IP und die Pipeline funktioniert ohne Unterbrechungen. In diesem Artikel finden Sie Schritt-für-Schritt-Anleitungen für GitHub Actions, GitLab CI und Jenkins.

Warum Proxys in CI/CD: reale Szenarien

CI/CD-Pipelines laufen auf Servern mit festen IP-Adressen – Cloud-Runnern von GitHub, GitLab oder auf eigenen Jenkins-Agenten. Diese IPs sind gut bekannt, und viele externe Dienste blockieren sie entweder oder beschränken die Anzahl der Anfragen. Hier sind konkrete Situationen, in denen man ohne Proxy nicht auskommt:

Zugriff auf geo-eingeschränkte Ressourcen

Viele Unternehmens-npm-Registries, Maven-Repositories und interne APIs sind nur aus bestimmten Ländern oder IP-Bereichen zugänglich. Wenn Ihr GitHub Actions-Runner sich in einer Region befindet, die auf Firewall-Ebene des Zielservices blockiert ist, kann die Pipeline keine Abhängigkeiten herunterladen oder Daten senden. Ein Proxy mit der richtigen Geolokalisierung löst dieses Problem, ohne die Infrastruktur zu ändern.

Rate Limiting und IP-Blockierungen

Cloud-Runner von GitHub Actions verwenden IPs aus den Bereichen von Microsoft Azure. Viele öffentliche APIs kennen diese Bereiche und wenden strenge Limits an – oder blockieren sie vollständig. Zum Beispiel das Parsen öffentlicher Daten, Anfragen an Drittanbieter-APIs während Tests, das Herunterladen von Distributionen von eingeschränkten CDNs – all dies bricht regelmäßig aufgrund der IPs von Cloud-Runnern zusammen. Die Rotation über Proxys ermöglicht es, Rate Limiting zu umgehen.

Integrationstests mit echten Websites

Wenn Ihre Integrationstests auf echte Websites oder Marktplätze (Wildberries, Ozon, Avito, Amazon) zugreifen, sehen diese Websites bei jedem Start dieselbe IP vom Runner und blockieren sie schnell. Ein Proxy mit IP-Rotation ermöglicht es den Tests, stabil ohne Captchas und Blockierungen zu laufen.

Zugriff auf interne Unternehmensressourcen

Unternehmensnetzwerke sind oft vom externen Zugriff abgeschottet. Wenn die Pipeline auf einen internen Server deployen oder auf eine geschlossene API zugreifen muss, wird ein Proxy (oder SOCKS5-Tunnel) innerhalb des Unternehmensnetzwerks zur Brücke zwischen dem Cloud-Runner und der geschlossenen Infrastruktur.

Testen von Werbe- und Marketingintegrationen

Teams, die mit der Facebook Ads API, TikTok Ads API oder Google Ads API arbeiten, automatisieren häufig die Erstellung von Kampagnen über CI/CD. Diese Plattformen haben strenge IP-Regeln: Anfragen von IPs von Rechenzentren können blockiert oder erfordern zusätzliche Verifizierung. Residente Proxys in der Pipeline machen die Anfragen ähnlich wie normalen Benutzerverkehr.

Welchen Proxy-Typ für die Pipeline wählen

Die Wahl des Proxy-Typs hängt von der Aufgabe ab. Für CI/CD-Pipelines sind drei Optionen relevant – jede hat ihre eigenen Vor- und Nachteile:

Proxy in GitHub Actions einrichten

GitHub Actions ist das derzeit beliebteste CI/CD-Tool. Die Einrichtung eines Proxys erfolgt hier über Umgebungsvariablen und Repository-Geheimnisse. Lassen Sie uns das Schritt für Schritt durchgehen.

Schritt 1: Fügen Sie die Proxy-Daten zu den Repository-Geheimnissen hinzu

Schreiben Sie niemals den Benutzernamen und das Passwort des Proxys direkt in die YAML-Datei des Workflows. Verwenden Sie GitHub Secrets:

1. Öffnen Sie das Repository → Einstellungen → Secrets und Variablen → Actions
2. Klicken Sie auf Neues Repository-Geheimnis
3. Erstellen Sie ein Geheimnis PROXY_URL mit dem Wert http://user:[email protected]:port

Schritt 2: Verwenden Sie Umgebungsvariablen im Workflow

Die meisten Tools (curl, wget, npm, pip, Maven) erfassen automatisch die Standard-Umgebungsvariablen HTTP_PROXY, HTTPS_PROXY und NO_PROXY. Beispiel-Workflow:

name: Build mit 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: Abhängigkeiten installieren
        run: npm ci

      - name: Integrationstests ausführen
        run: npm test

      - name: Externe API aufrufen
        run: |
          curl -v https://api.example.com/data

Schritt 3: SOCKS5-Proxy in GitHub Actions

Wenn Sie SOCKS5 verwenden (was für die meisten Aufgaben empfohlen wird), sind die Standard-Umgebungsvariablen nicht ausreichend – ein lokaler Tunnel ist erforderlich. Verwenden Sie das Tool proxychains oder konfigurieren Sie microsocks:

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

      - name: Befehl über SOCKS5 ausführen
        run: proxychains4 curl https://restricted-resource.com/api

Proxy für bestimmte Tools einrichten

Einige Tools ignorieren Systemvariablen und erfordern eine separate Konfiguration:

Proxy in GitLab CI einrichten

GitLab CI bietet mehrere Ebenen zur Festlegung von Umgebungsvariablen: auf Projektebene, Gruppenebene oder Instanzebene. Dies macht die Verwaltung von Proxys flexibler im Vergleich zu GitHub Actions.

Schritt 1: Fügen Sie Variablen zu GitLab CI/CD Variables hinzu

1. Öffnen Sie das Projekt → Einstellungen → CI/CD → Abschnitt Variablen
2. Klicken Sie auf Variable hinzufügen
3. Fügen Sie die Variable PROXY_URL mit dem Typ Masked (versteckt den Wert in den Logs) hinzu
4. Wert: http://user:[email protected]:port

Schritt 2: Verwenden Sie Variablen 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 nur für bestimmte Jobs

Wenn der Proxy nicht überall benötigt wird (z. B. nur für Integrationstests, aber nicht für den Build), setzen Sie die Variablen auf der Ebene des spezifischen Jobs und nicht global:

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

build:
  stage: build
  # Hier ist kein Proxy gesetzt – direkte Verbindung
  script:
    - npm ci && npm run build

Self-hosted GitLab Runner: Proxy auf Runner-Ebene einrichten

Wenn Sie einen eigenen GitLab Runner verwenden, können Sie den Proxy global in der Runner-Konfiguration festlegen. Öffnen Sie die Datei /etc/gitlab-runner/config.toml und fügen Sie im Abschnitt [runners.env] hinzu:

[[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"
  ]

Dies ist praktisch, wenn alle Pipelines auf diesem Runner den Proxy verwenden sollen – es ist nicht notwendig, ihn in jeder .gitlab-ci.yml zu definieren.

Proxy in Jenkins einrichten

Jenkins ist das flexibelste der drei Tools, aber auch das komplexeste in der Einrichtung. Proxys können hier auf mehreren Ebenen festgelegt werden: global für Jenkins, für einen bestimmten Pipeline oder für einen einzelnen Schritt.

Methode 1: Globale Proxy-Einstellungen in Jenkins

1. Öffnen Sie Manage Jenkins → System
2. Finden Sie den Abschnitt HTTP Proxy Configuration
3. Füllen Sie die Felder aus: Server, Port, Benutzername, Passwort
4. Geben Sie im Feld No Proxy Host interne Adressen durch Kommas getrennt an
5. Klicken Sie auf Test URL, um zu überprüfen, und speichern Sie

Diese Einstellung beeinflusst das Laden von Plugins und Updates für Jenkins selbst, wird jedoch nicht automatisch an die Ausführungsumgebung der Pipelines weitergegeben. Für Pipelines ist eine separate Konfiguration erforderlich.

Methode 2: Proxy im Declarative Pipeline über 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}"
                '''
            }
        }
    }
}

Schritt 3: Fügen Sie die Proxy-Anmeldeinformationen zu Jenkins Credentials hinzu

1. Öffnen Sie Manage Jenkins → Credentials → System → Globale Anmeldeinformationen
2. Klicken Sie auf Anmeldeinformationen hinzufügen
3. Typ: Geheimer Text
4. ID: proxy-url-credential
5. Geheimnis: http://user:[email protected]:port

Methode 3: Proxy über JVM-Parameter für Java-Projekte

Wenn Ihre Pipeline ein Java-Projekt (Maven, Gradle) erstellt, funktionieren die System-Umgebungsvariablen möglicherweise nicht – die JVM verwendet eigene System-Eigenschaften. Fügen Sie diese in JAVA_OPTS hinzu:

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 innerhalb von Docker-Containern in der Pipeline

Die meisten modernen CI/CD-Pipelines führen Schritte innerhalb von Docker-Containern aus. Das Übertragen des Proxys in den Container ist eine separate Aufgabe, die auf verschiedene Weise gelöst werden kann.

Proxy über --build-arg beim Erstellen des Images übergeben

Wenn der Proxy nur während des Build-Prozesses des Docker-Images benötigt wird (z. B. zum Installieren von Paketen innerhalb des Dockerfiles), verwenden Sie Build-Argumente:

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

Globale Docker-Daemon-Einstellung für Proxys

Auf selbst gehosteten Runnern kann der Proxy für den gesamten Docker-Daemon konfiguriert werden – dann erhalten alle Container automatisch den Proxy, ohne Änderungen im 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"

# Änderungen anwenden:
# systemctl daemon-reload
# systemctl restart docker

Sicherheit: Wie man Proxy-Anmeldeinformationen speichert

Proxy-Anmeldeinformationen sind ebenso geheim wie API-Schlüssel oder Passwörter für Datenbanken. Ein Leck dieser Informationen bedeutet, dass jeder Ihren Proxy auf Ihre Kosten nutzen kann. Hier sind die Regeln für die sichere Speicherung:

Sicherheits-Checkliste

• ✅ Nie den Benutzernamen/Passwort des Proxys direkt in YAML-Dateien der Pipeline schreiben
• ✅ Verwenden Sie Masked variables in GitLab und Encrypted secrets in GitHub – sie werden in den Logs verborgen
• ✅ Verwenden Sie in Jenkins den Typ Secret text oder Username with password im Credentials Store
• ✅ Fügen Sie NO_PROXY für interne Adressen hinzu – der Verkehr zu Ihrer Infrastruktur sollte nicht über den Proxy gehen
• ✅ Rotieren Sie regelmäßig die Passwörter des Proxys – aktualisieren Sie nur im Geheimnisspeicher, ohne den Code der Pipeline zu ändern
• ✅ Verwenden Sie die IP-Authentifizierung des Proxys (Whitelist der IP des Runners), wo dies unterstützt wird – das ist sicherer als ein Passwort
• ✅ Überprüfen Sie die Logs des Proxys auf ungewöhnliche Aktivitäten

Proxy-URL-Format: Was wo eingefügt wird

Häufige Fehler und wie man sie behebt

Selbst nach der richtigen Einrichtung können Probleme auftreten. Hier sind die häufigsten Fehler und deren Lösungen:

Fehler: Proxy-Authentifizierung erforderlich (407)

Fehler: SSL-Zertifikatsüberprüfung fehlgeschlagen

Fehler: Verbindungstimeout über Proxy

Fehler: Tool ignoriert die HTTP_PROXY-Variablen

Fehler: Interne Dienste gehen ebenfalls über den Proxy

Fazit

Die Einrichtung eines Proxys in der CI/CD-Pipeline ist keine einmalige Aufgabe, sondern Teil einer richtigen Automatisierungsarchitektur. Wir haben drei Hauptwerkzeuge behandelt: GitHub Actions (über Secrets und Umgebungsvariablen), GitLab CI (über Variablen mit Maskierung) und Jenkins (über Credentials Store und Declarative Pipeline). Die Schlüsselprinzipien sind für alle gleich: niemals Anmeldeinformationen im Code speichern, NO_PROXY für interne Adressen verwenden und den Proxy-Typ je nach spezifischer Aufgabe auswählen.

Die Wahl des richtigen Proxy-Typs ist entscheidend für die Stabilität der Pipeline. Für das Herunterladen von Abhängigkeiten und den Zugriff auf Standard-APIs sind schnelle Rechenzentrums-Proxys ausreichend. Wenn Ihre Pipeline jedoch Integrationstests auf echten Websites durchführt, mit Werbeplattformen (Facebook Ads API, TikTok Ads API) arbeitet oder auf Marktplätze zugreift – verwenden Sie residente Proxys: Ihre IPs werden als normaler Benutzerverkehr wahrgenommen und unterliegen äußerst selten Blockierungen oder Rate Limiting.

Die wichtigste Regel: Testen Sie den Proxy als separaten Schritt zu Beginn der Pipeline – dies ermöglicht eine schnelle Diagnose von Problemen und spart Zeit bei der Fehlersuche am Ende eines langen Builds. Fügen Sie den Schritt curl -v https://api.ipify.org sofort nach der Proxy-Einrichtung hinzu – er zeigt die IP, von der die Anfragen ausgehen, und bestätigt, dass das Proxying korrekt funktioniert.