Proxys für GitLab: So richten Sie den Zugriff für Ihr Team und CI/CD-Pipelines ohne Unterbrechungen ein

```html

GitLab ist eine beliebte Plattform zur Codeverwaltung und für DevOps-Prozesse, die von Tausenden von Teams weltweit genutzt wird. Aber was tun, wenn der Zugang zu GitLab auf der Ebene des Anbieters, des Unternehmensnetzwerks oder eines ganzen Landes blockiert ist? Noch schlimmer ist es, wenn die CI/CD-Pipeline mitten in der Nacht ausfällt, nur weil der Runner nicht auf das Repository zugreifen kann.

In diesem Artikel werden wir erläutern, wie man einen Proxy für GitLab auf der Ebene des Git-Clients, des GitLab Runners und des Unternehmensservers einrichtet, damit das gesamte Team stabil von überall auf der Welt arbeiten kann.

Warum ein Proxy für GitLab benötigt wird: reale Szenarien

Bevor Sie einen Proxy einrichten, ist es wichtig zu verstehen, welches Problem Sie genau lösen. Die Situationen sind unterschiedlich, und das beeinflusst die Wahl des Proxy-Typs und die Art seiner Anbindung.

Szenario 1: GitLab wird vom Anbieter oder auf Landesebene blockiert

In einigen Ländern und Unternehmensnetzwerken ist der Zugang zu gitlab.com eingeschränkt. Ein Entwickler öffnet das Terminal, gibt git pull ein – und erhält einen Timeout. In diesem Fall fungiert der Proxy als Vermittler: Der Datenverkehr geht nicht direkt zu gitlab.com, sondern über einen Zwischenserver in einem Land, in dem es keine Einschränkungen gibt.

Szenario 2: Verteiltes Team in verschiedenen Ländern

Stellen Sie sich vor: Ein Teil des Teams arbeitet aus Russland, ein Teil aus Kasachstan, ein Teil aus Europa. Jeder hat unterschiedliche Netzwerkbedingungen und Einschränkungen. Damit alle stabil und mit gleicher Geschwindigkeit arbeiten können, richten Unternehmen einen Unternehmensproxy-Server ein, über den der gesamte Datenverkehr zu GitLab über einen einheitlichen Kanal läuft.

Szenario 3: CI/CD Runner kann nicht auf externe Abhängigkeiten zugreifen

GitLab Runner startet die Pipeline, und in der Phase npm install oder pip install bricht alles ab – weil der Server, auf dem der Runner läuft, sich in einem geschlossenen Netzwerk ohne direkten Internetzugang befindet. Der Proxy ermöglicht es dem Runner, externe Abhängigkeiten zu beziehen, ohne dem gesamten Server vollen Internetzugang zu gewähren.

Szenario 4: Selbstgehostetes GitLab hinter einer Unternehmensfirewall

Das Unternehmen betreibt einen eigenen GitLab-Server im internen Netzwerk. Entwickler im Homeoffice müssen sich damit verbinden. Anstatt ein VPN für den gesamten Datenverkehr einzurichten, kann ein Proxy nur für den GitLab-Datenverkehr eingerichtet werden – das ist schneller und einfacher zu verwalten.

Szenario 5: Überwachung und Audit des Datenverkehrs

Große Unternehmen leiten den gesamten Datenverkehr zu den Repositories über einen Unternehmensproxy, um die Aktivität zu protokollieren, zu kontrollieren, wer was pusht, und unerwünschte Operationen zu blockieren. Dies ist eine Sicherheitsanforderung und keine Umgehung von Blockaden.

Wichtig zu verstehen vor der Einrichtung:

Ein Proxy für GitLab kann auf drei Ebenen gleichzeitig erforderlich sein: auf dem Rechner des Entwicklers (Git-Client), auf dem Server mit GitLab Runner (CI/CD) und auf dem GitLab-Server selbst (wenn selbstgehostet). Jede Ebene wird separat konfiguriert.

Welcher Proxy-Typ für GitLab geeignet ist

GitLab funktioniert über die Protokolle HTTPS und SSH. Das bestimmt sofort, welche Proxy-Typen anwendbar sind und welche nicht. Lassen Sie uns die Optionen durchgehen.

Proxy-Typ	Protokoll	Geeignet für GitLab	Wann verwenden
HTTP/HTTPS-Proxy	HTTP, HTTPS	✓ Ja	Git über HTTPS, Web-Interface von GitLab
SOCKS5-Proxy	TCP (beliebig)	✓ Ja (beste Option)	Git über HTTPS und SSH, CI/CD
SOCKS4-Proxy	TCP	~ Teilweise	Nur wenn kein SOCKS5 verfügbar ist
Transparenter Proxy	HTTP	✗ Nein	Nicht geeignet – umgeht keine Blockaden

Für die Arbeit mit GitLab ist die optimale Wahl ein SOCKS5. Er funktioniert auf der TCP-Ebene und proxyiert sowohl HTTPS-Verbindungen (Web-Interface, git clone über HTTPS) als auch SSH-Verbindungen (git push/pull über SSH auf Port 22 oder 443) gleich gut.

Residential vs. Datacenter-Proxys für GitLab

Hier hängt alles von der Aufgabe ab. Wenn das Ziel darin besteht, eine Blockade durch GeoIP zu umgehen oder eine stabile IP für die Authentifizierung zu erhalten, sind Datacenter-Proxys geeignet – sie sind schneller, günstiger und bieten eine niedrige Latenz, was bei der Arbeit mit großen Repositories entscheidend ist.

Wenn jedoch Ihre Unternehmens-IP auf die Blockliste von GitLab geraten ist (was bei aggressivem Scannen oder nach Sicherheitsvorfällen vorkommen kann), sollten Sie Residential-Proxys in Betracht ziehen – deren IP-Adressen gehören echten Haushaltsnutzern und werden von Plattformen äußerst selten blockiert.

Proxy für den Git-Client einrichten (global)

Dies ist das häufigste Szenario: Ein Entwickler kann sich nicht mit GitLab auf seinem Rechner verbinden. Die Einrichtung erfolgt über die Konfiguration von Git selbst – einmalig, und sie funktioniert für alle Repositories.

Option A: HTTPS-Proxy für Git

Wenn Sie mit GitLab über HTTPS arbeiten (die Repository-Adresse beginnt mit https://), führen Sie im Terminal Folgendes aus:

# HTTP-Proxy global einrichten
git config --global http.proxy http://IHRE_PROXY_IP:PORT

# Wenn der Proxy Authentifizierung erfordert
git config --global http.proxy http://BENUTZERNAME:PASSWORT@IHRE_PROXY_IP:PORT

# Für SOCKS5-Proxy (empfohlen)
git config --global http.proxy socks5://IHRE_PROXY_IP:PORT

# Überprüfen, ob die Einstellung angewendet wurde
git config --global --get http.proxy

Option B: Proxy nur für gitlab.com (beeinflusst andere Repositories nicht)

Wenn Sie nicht möchten, dass der Proxy auf alle Git-Operationen angewendet wird (zum Beispiel wenn GitHub oder Bitbucket normal funktionieren), können Sie den Proxy nur für eine bestimmte Domain einrichten:

# Proxy nur für gitlab.com
git config --global http.https://gitlab.com.proxy socks5://IHRE_PROXY_IP:PORT

# Oder für Ihr selbstgehostetes GitLab
git config --global http.https://git.IHR_UNTERNEHMEN.com.proxy socks5://IHRE_PROXY_IP:PORT

Option C: SSH über Proxy (für diejenigen, die über SSH arbeiten)

Wenn Sie Repositories über SSH klonen ([email protected]:...), erfolgt die Proxy-Einrichtung in der SSH-Konfiguration und nicht in Git. Öffnen Sie die Datei ~/.ssh/config und fügen Sie hinzu:

# Für Linux/macOS – über nc (netcat)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand nc -X 5 -x IHRE_PROXY_IP:PORT %h %p

# Für Windows – über connect.exe (Git für Windows)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand connect -S IHRE_PROXY_IP:PORT %h %p

Nach der Einrichtung überprüfen Sie die Verbindung mit dem Befehl ssh -T [email protected]. Wenn alles richtig eingerichtet ist, sehen Sie eine Willkommensnachricht von GitLab.

Wie man den Proxy deaktiviert, wenn er nicht mehr benötigt wird

# Globalen Proxy entfernen
git config --global --unset http.proxy

# Proxy für eine bestimmte Domain entfernen
git config --global --unset http.https://gitlab.com.proxy

Proxy für GitLab Runner und CI/CD-Pipelines

GitLab Runner ist ein Agent, der Aufgaben aus .gitlab-ci.yml ausführt. Wenn der Runner sich in einem geschlossenen Netzwerk oder auf einem Server mit eingeschränktem Internetzugang befindet, muss der Proxy separat eingerichtet werden. Die Einstellungen des Git-Clients des Entwicklers helfen hier nicht – der Runner arbeitet auf einem anderen Rechner.

Methode 1: Umgebungsvariablen in der Runner-Konfiguration

Öffnen Sie die Konfigurationsdatei des GitLab Runners (normalerweise /etc/gitlab-runner/config.toml) und fügen Sie die Umgebungsvariablen in den Abschnitt [runners.env] hinzu:

[[runners]]
  name = "mein-runner"
  url = "https://gitlab.com/"
  token = "IHRE_TOKEN"
  executor = "shell"
  environment = [
    "HTTP_PROXY=http://IHRE_PROXY_IP:PORT",
    "HTTPS_PROXY=http://IHRE_PROXY_IP:PORT",
    "NO_PROXY=localhost,127.0.0.1,ihre-intern-domain.com"
  ]

Nach der Änderung der Konfiguration starten Sie den Runner neu: sudo gitlab-runner restart

Methode 2: Variablen in .gitlab-ci.yml (auf Pipeline-Ebene)

Wenn Sie nicht der Administrator des Runners sind oder den Proxy nur für ein bestimmtes Projekt einrichten möchten, fügen Sie die Variablen direkt in die Pipeline-Datei ein:

variables:
  HTTP_PROXY: "http://IHRE_PROXY_IP:PORT"
  HTTPS_PROXY: "http://IHRE_PROXY_IP:PORT"
  NO_PROXY: "localhost,127.0.0.1,.internal.company.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - npm install   # jetzt über den Proxy
    - npm run build

Methode 3: Variablen in den GitLab-Projekteinstellungen (ohne Commit in das Repository)

Die beste Methode für sensible Daten (Proxy mit Authentifizierung): Gehen Sie zu Settings → CI/CD → Variables Ihres Projekts und fügen Sie die Variablen HTTP_PROXY, HTTPS_PROXY, NO_PROXY als geschützte (masked) Variablen hinzu. Sie sind automatisch in allen Pipelines verfügbar, werden aber nicht in den Logs angezeigt.

Proxy für Docker-Executor

Wenn der Runner den Docker-Executor verwendet, erben die Container standardmäßig nicht die Proxy-Einstellungen des Hosts. Sie müssen entweder die Variablen in config.toml im Abschnitt [runners.docker] hinzufügen oder eine Datei /etc/systemd/system/docker.service.d/proxy.conf auf dem Host mit dem Runner erstellen:

[Service]
Environment="HTTP_PROXY=http://IHRE_PROXY_IP:PORT"
Environment="HTTPS_PROXY=http://IHRE_PROXY_IP:PORT"
Environment="NO_PROXY=localhost,127.0.0.1"

Danach: sudo systemctl daemon-reload && sudo systemctl restart docker

Proxy für selbstgehostete GitLab-Server

Wenn Sie einen eigenen GitLab-Server (installiert über Omnibus oder Helm) verwalten, wird ein Proxy benötigt, damit GitLab auf externe Dienste zugreifen kann: Benachrichtigungen senden, sich mit externen CI-Systemen verbinden, Benutzeravatare hochladen, sich mit Jira oder Slack integrieren.

Einrichtung in gitlab.rb (Omnibus-Installation)

Öffnen Sie die Datei /etc/gitlab/gitlab.rb und fügen Sie die folgenden Zeilen hinzu oder kommentieren Sie sie aus:

# Proxy für GitLab (Omnibus)
gitlab_rails['env'] = {
  "http_proxy" => "http://IHRE_PROXY_IP:PORT",
  "https_proxy" => "http://IHRE_PROXY_IP:PORT",
  "no_proxy" => "localhost,127.0.0.1,IHR_INTERNER_DOMEN"
}

# Wenn der Proxy Authentifizierung erfordert:
gitlab_rails['env'] = {
  "http_proxy" => "http://BENUTZERNAME:PASSWORT@IHRE_PROXY_IP:PORT",
  "https_proxy" => "http://BENUTZERNAME:PASSWORT@IHRE_PROXY_IP:PORT",
  "no_proxy" => "localhost,127.0.0.1"
}

Nach der Änderung der Konfiguration wenden Sie die Einstellungen an: sudo gitlab-ctl reconfigure

Einrichtung ausgehender Verbindungen über das Admin-Bereich

In GitLab 15.0+ gibt es die Möglichkeit, einen Proxy direkt über die Weboberfläche einzurichten: Gehen Sie zu Admin Area → Settings → Network → Outbound requests. Hier können Sie einen Proxy für ausgehende Webhooks angeben und die IP-Bereiche einschränken, auf die GitLab zugreifen kann. Dies ist nützlich für die Sicherheit – es verhindert SSRF-Angriffe über Webhooks.

Zugangsorganisation für das gesamte Team über Proxy

Wenn ein stabiler Zugang zu GitLab für ein Team von 5–50 Personen gewährleistet werden muss, ist die individuelle Einrichtung auf jedem Rechner nicht der beste Ansatz. Lassen Sie uns skalierbarere Lösungen betrachten.

Ansatz 1: Unternehmensproxy-Server

Ein Proxy-Server (z. B. Squid oder 3proxy) mit Internetzugang wird eingerichtet. Alle Entwickler konfigurieren Git so, dass dieser Server verwendet wird. Vorteile: zentrale Verwaltung, einheitlicher Kontrollpunkt, Datenverkehr kann protokolliert werden. Nachteil: Der Server wird zum einzigen Fehlerpunkt.

Ansatz 2: Repository-Mirror

GitLab unterstützt das Mirroring von Repositories. Sie können ein selbstgehostetes GitLab im internen Netzwerk als Mirror von gitlab.com einrichten. Entwickler arbeiten mit dem internen Server, und dieser synchronisiert sich über den Proxy mit dem externen. Dies verringert die Abhängigkeit von der Qualität der Proxy-Verbindung für jeden Entwickler.

Ansatz 3: Automatische Einrichtung über Dotfiles oder Onboarding-Skript

Für Teams, in denen jeder Entwickler seine Umgebung selbst einrichtet, ist es praktisch, ein Onboarding-Skript zu erstellen, das die erforderlichen Git-Einstellungen automatisch konfiguriert. Das Skript wird im Unternehmensrepository gespeichert und beim Einrichten eines neuen Arbeitsplatzes ausgeführt.

#!/bin/bash
# setup-git-proxy.sh – beim Einrichten eines neuen Arbeitsplatzes ausführen

PROXY_HOST="proxy.company.com"
PROXY_PORT="3128"

echo "Einrichtung des Git-Proxys für den Zugang zu GitLab..."
git config --global http.https://gitlab.com.proxy "socks5://${PROXY_HOST}:${PROXY_PORT}"
git config --global http.sslVerify true
echo "Fertig! Überprüfen Sie: git config --global --list | grep proxy"

Checkliste für die Teambereitstellung

• Bestimmen, ob ein Proxy auf der Ebene der Entwickler, Runner oder des GitLab-Servers (oder allen drei) benötigt wird
• Proxy-Typ wählen: SOCKS5 für maximale Kompatibilität
• NO_PROXY für alle internen Domains und Dienste einrichten
• Überprüfen, ob SSH-Schlüssel über den Proxy funktionieren (ein separater Schritt!)
• Dokumentieren Sie die Einstellungen in der Unternehmenswiki
• Erstellen Sie ein Onboarding-Skript für neue Mitarbeiter
• Überwachen Sie die Verfügbarkeit des Proxy-Servers

Häufige Probleme und deren Lösungen

Selbst nach einer korrekten Einrichtung läuft manchmal etwas schief. Hier sind die häufigsten Probleme und deren Diagnose.

Problem 1: SSL-Zertifikatproblem: Lokalen Ausstellerzertifikat nicht erhalten

Dieser Fehler tritt auf, wenn der Proxy-Server (insbesondere ein Unternehmensproxy) eine SSL-Inspektion durchführt – das Zertifikat von GitLab durch sein eigenes ersetzt. Git vertraut diesem Zertifikat nicht. Lösung: Fügen Sie das Unternehmensstammzertifikat zu den vertrauenswürdigen hinzu.

# Temporäre Lösung (für Debugging, nicht für die Produktion!)
git config --global http.sslVerify false

# Richtige Lösung: Unternehmenszertifikat hinzufügen
git config --global http.sslCAInfo /pfad/zum/corporate-ca-bundle.crt

Problem 2: Proxy funktioniert für HTTPS, aber SSH funktioniert nicht

Dies ist eine klassische Situation: Sie haben http.proxy in Git konfiguriert, das HTTPS-Klonen funktioniert, aber SSH-Operationen funktionieren immer noch nicht. Grund: Der SSH-Datenverkehr geht nicht über den HTTP-Proxy. Sie müssen ~/.ssh/config separat einrichten, wie im Abschnitt über den Git-Client beschrieben.

Alternative: Wechseln Sie zur Arbeit mit GitLab über HTTPS anstelle von SSH. Ändern Sie dazu die Remote-URL:

# Aktuellen Remote überprüfen
git remote -v

# Von SSH auf HTTPS ändern
git remote set-url origin https://gitlab.com/benutzername/repo.git

Problem 3: CI/CD-Pipeline hängt beim Klonen des Repositories

Der Runner klont das Repository direkt von GitLab unter Verwendung eines Tokens. Wenn der Runner hinter einem Proxy ist, muss auch dieses Klonen über den Proxy erfolgen. Stellen Sie sicher, dass die Variablen HTTP_PROXY und HTTPS_PROXY in config.toml gesetzt sind und nicht nur in .gitlab-ci.yml – die Variablen aus der CI-Datei werden nach dem Klonen und nicht davor angewendet.

Problem 4: Proxy funktioniert, aber sehr langsam

Wenn Push/Pull funktionieren, aber 5–10 Mal länger dauern als gewöhnlich, kann das Problem in der Bandbreite des Proxy-Servers oder seiner geografischen Lage liegen. Bei der Arbeit mit großen Repositories (100+ MB) ist es wichtig, einen Proxy mit niedriger Latenz und hoher Bandbreite zu wählen. Datacenter-Proxys sind in diesem Fall vorzuziehen, da sie einen stabileren Kanal bieten.

Problem 5: Authentifizierung über Proxy erfordert wiederholte Eingabe des Passworts

Wenn der Proxy eine Basis-Authentifizierung erfordert und Git jedes Mal nach dem Passwort fragt, richten Sie den Credential Helper ein:

# macOS – Schlüsselbund verwenden
git config --global credential.helper osxkeychain

# Windows – Windows Credential Manager verwenden
git config --global credential.helper manager

# Linux – für 1 Stunde cachen
git config --global credential.helper "cache --timeout=3600"

Fazit und Empfehlungen

Die Einrichtung eines Proxys für GitLab ist eine Aufgabe, die auf mehreren Ebenen gleichzeitig gelöst werden muss. Ein Entwickler auf seinem Arbeitsplatzrechner muss nur ein paar Zeilen in der Git- oder SSH-Konfiguration eintragen. Für CI/CD müssen Umgebungsvariablen in die Konfiguration des Runners oder die Projekteinstellungen hinzugefügt werden. Und für selbstgehostetes GitLab muss gitlab.rb aktualisiert und die Konfiguration neu erstellt werden.

Die wichtigsten Regeln, die helfen, die meisten Probleme zu vermeiden:

• Verwenden Sie SOCKS5 – er funktioniert sowohl mit HTTPS als auch mit SSH
• Richten Sie immer NO_PROXY für interne Dienste ein
• Deaktivieren Sie die SSL-Überprüfung in der Produktion nicht – fügen Sie das Unternehmenszertifikat hinzu
• Für CI/CD den Proxy in config.toml einrichten und nicht nur in .gitlab-ci.yml
• Dokumentieren Sie die Einstellungen – neue Entwickler im Team werden es Ihnen danken

Wenn Sie nach einem zuverlässigen Proxy suchen, um stabilen Zugang zu GitLab von überall auf der Welt zu gewährleisten, empfehlen wir, Datacenter-Proxys in Betracht zu ziehen – sie bieten hohe Datenübertragungsraten und niedrige Latenz, was besonders wichtig ist, wenn Sie mit großen Repositories und intensiven CI/CD-Pipelines arbeiten. Für Teams, die maximale Anonymität oder die Umgehung von GeoIP-Blockaden benötigen, sind Residential-Proxys mit IP-Adressen echter Haushaltsnutzer geeignet.