Proxy-Einrichtung in GitHub Actions und CI/CD

Proxy-Einrichtung in GitHub Actions und CI/CD beinhaltet die Konfiguration standardmäßiger Proxy-Umgebungsvariablen wie HTTP_PROXY, HTTPS_PROXY und NO_PROXY innerhalb Ihrer Workflow-Definition, typischerweise auf Job- oder Schritt-Ebene. Dies ermöglicht es Aktionen, Skripten und Tools, die innerhalb der CI/CD-Pipeline ausgeführt werden, ihren Netzwerkverkehr über einen bestimmten Proxy-Server zu leiten.

Organisationen setzen häufig Proxy-Server ein, um den ausgehenden Netzwerkzugriff zu kontrollieren, Sicherheitsrichtlinien durchzusetzen, Inhalte zu filtern und häufig aufgerufene Ressourcen zwischenzuspeichern. Für CI/CD-Pipelines, die in solchen Umgebungen betrieben werden, ist die Konfiguration von Proxy-Einstellungen unerlässlich, damit Build-Tools, Abhängigkeitsmanager und Testskripte externe Dienste, Paket-Repositories oder APIs erreichen können. GitHub Actions Runner, insbesondere selbstgehostete Runner, benötigen möglicherweise eine Proxy-Konfiguration, um GitHub selbst oder andere Internetressourcen zu erreichen.

Proxy-Umgebungsvariablen einstellen

Die gängigste und universell anerkannte Methode zur Konfiguration eines Proxys in einer Linux-basierten Umgebung (die von GitHub-gehosteten Runnern hauptsächlich verwendet wird) ist über Umgebungsvariablen.

• HTTP_PROXY: Gibt den Proxy-Server für HTTP-Anfragen an.
• HTTPS_PROXY: Gibt den Proxy-Server für HTTPS-Anfragen an.
• NO_PROXY: Eine durch Kommas getrennte Liste von Hostnamen, Domänen oder IP-Adressen, die den Proxy umgehen sollen. Dies ist entscheidend für den direkten Zugriff auf interne Ressourcen.

Das Format für HTTP_PROXY und HTTPS_PROXY ist typischerweise http://[user:password@]host:port.
Sowohl Großbuchstaben (HTTP_PROXY) als auch Kleinbuchstaben (http_proxy) dieser Variablen werden oft von verschiedenen Tools berücksichtigt; die Verwendung von Großbuchstaben ist Standardpraxis für Umgebungsvariablen.

Proxy-Konfiguration auf Workflow-Ebene

Das Anwenden von Proxy-Einstellungen auf Job-Ebene stellt sicher, dass alle Schritte innerhalb dieses Jobs die Konfiguration erben.

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

Proxy-Konfiguration auf Schritt-Ebene

Für Szenarien, die unterschiedliche Proxy-Einstellungen für bestimmte Schritte erfordern oder um Job-Level-Einstellungen zu überschreiben, können Umgebungsvariablen auf Schritt-Ebene definiert werden.

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

jobs:
  build:
    runs-on: ubuntu-latest
    env: # Default proxy for the job (if any)
      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

Proxy-Authentifizierung mit Secrets

Wenn Ihr Proxy eine Authentifizierung erfordert, fügen Sie den Benutzernamen und das Passwort direkt in die Proxy-URL ein. Speichern Sie aus Sicherheitsgründen Anmeldeinformationen als GitHub Actions Secrets und referenzieren Sie diese im Workflow.

Erstellen Sie zunächst Repository-Secrets (z.B. PROXY_USER, PROXY_PASS) in Ihren GitHub-Repository-Einstellungen.

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 # or curl, etc.

Gängige Tools und Proxy-Interaktion

Während HTTP_PROXY und HTTPS_PROXY weitgehend respektiert werden, bieten einige Tools spezifische Konfigurationsmethoden.

git-Befehle

git berücksichtigt im Allgemeinen HTTP_PROXY und HTTPS_PROXY für Remote-Operationen. Für eine explizite Konfiguration oder in Fällen, in denen Umgebungsvariablen nicht ausreichen, kann git config verwendet werden.

# Set proxy for HTTP and HTTPS git operations
git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy http://proxy.example.com:8080

# Configure a specific proxy for a particular remote
git config http.https://github.com/.proxy http://github-proxy:8080

npm, yarn

Node.js-Paketmanager wie npm und yarn respektieren die Umgebungsvariablen HTTP_PROXY und HTTPS_PROXY. Sie bieten auch eigene Konfigurationsbefehle für persistente Einstellungen.

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

# Using 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 (Image-Build und Container-Laufzeit)

Proxy-Einstellungen für Docker erfordern eine spezifische Handhabung sowohl für die Image-Build-Zeit als auch für die Container-Laufzeit.

Docker Build-Time Proxy

Für Befehle, die während eines docker build ausgeführt werden (z.B. RUN apk add, RUN apt-get update), müssen Proxy-Einstellungen als Build-Argumente übergeben werden.

Dockerfile-Beispiel:

FROM alpine:latest

# Define build arguments for proxy settings
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Set environment variables for subsequent RUN commands
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

# Example: Use proxy for package installation
RUN apk add --no-cache curl

# ... rest of your Dockerfile

GitHub Actions Workflow-Schritt:

- 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

Docker Container-Laufzeit Proxy

Wenn Ihr Workflow einen Docker-Container ausführt (z.B. unter Verwendung des container:-Schlüssels oder docker run), müssen Proxy-Einstellungen als Umgebungsvariablen an den Container übergeben werden.

Verwendung des container:-Schlüssels:

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

Verwendung von docker run in einem Schritt:

- 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

Java-Anwendungen (Maven, Gradle)

Java-Anwendungen, einschließlich Build-Tools wie Maven und Gradle, erfordern typischerweise, dass Proxy-Einstellungen als Java-Systemeigenschaften übergeben werden. Dies geschieht üblicherweise über die Umgebungsvariablen MAVEN_OPTS oder _JAVA_OPTIONS.

# For 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'"

# For Gradle (also applies to other JVM-based tools)
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'"

Alternativ kann Maven über ~/.m2/settings.xml und Gradle über gradle.properties im Projekt- oder Benutzerverzeichnis konfiguriert werden.

Fehlerbehebung bei Proxy-Problemen

• Umgebungsvariablen überprüfen: Verwenden Sie run: env | grep -i proxy in einem Schritt, um zu bestätigen, dass die Proxy-Umgebungsvariablen korrekt gesetzt und für die Shell des Runners sichtbar sind.
• NO_PROXY überprüfen: Stellen Sie sicher, dass alle internen Hosts oder GitHub-Domänen korrekt in NO_PROXY aufgeführt sind, um unnötiges Proxying oder Routing-Probleme zu vermeiden.
• Proxy-Server-Logs: Überprüfen Sie, falls möglich, die Logs des Proxy-Servers auf Verbindungsversuche von der IP-Adresse des GitHub Actions Runners. Dies hilft festzustellen, ob die Anfrage den Proxy erreicht und warum sie möglicherweise abgelehnt wird (z.B. Authentifizierungsfehler, Zugriff verweigert).
• Netzwerkkonnektivität: Verwenden Sie curl -v --proxy <your-proxy-url> <target-url> innerhalb eines Workflow-Schritts, um die Konnektivität über den Proxy zu einem bekannten externen Endpunkt explizit zu testen.
• SSL/TLS-Zertifikatsprobleme: Wenn Sie einen HTTPS-Proxy verwenden oder HTTPS-Sites über einen HTTP-Proxy aufrufen und der Proxy eine SSL-Inspektion durchführt, kann der Runner auf Zertifikatsvalidierungsfehler stoßen. Dies erfordert, dass das Root-CA-Zertifikat des Proxys zum Trust Store des Runners hinzugefügt wird. Dies ist eine komplexe Konfiguration, die oft von selbstgehosteten Runner-Setups verwaltet wird.

Zusammenfassung der Proxy-Konfiguration