Proxy in GitHub Codespaces einrichten

GitHub Codespaces in einem eingeschränkten Netzwerk mit einem Proxy verwenden

Ein GitHub Codespace führt seinen Entwicklungscontainer in einer gehosteten Umgebung aus, während der Browser, in dem Sie ihn anzeigen, auf Ihrem eigenen Gerät läuft. Dieser Unterschied ist wichtig: Wenn Sie einen Proxy im Container konfigurieren, kann das Paket-Downloads aus dem Codespace umleiten. Wie Ihr lokaler Browser Websites erreicht, ändert sich dadurch jedoch nicht automatisch.

Schlägt die Installation einer Abhängigkeit hinter einer Unternehmens-Firewall fehl, finden Sie zunächst heraus, welche Verbindung blockiert wird. Davon hängt ab, wo der Proxy konfiguriert werden muss und was Ihre Organisation freigeben muss. Wenn Sie GitHub Codespaces hinter Unternehmens-Firewall nutzen, hilft diese Unterscheidung dabei, den richtigen Netzwerkpfad für die Fehlersuche zu finden.

1. Ermitteln, für welchen Codespaces-Datenverkehr der Proxy benötigt wird

Notieren Sie, welcher konkrete Vorgang fehlschlägt. Eine Python-Bibliothek mit pip zu installieren, eine Node.js-Abhängigkeit mit npm abzurufen oder ein Kommandozeilenprogramm über ein Terminal herunterzuladen – all das sind Anfragen von Software im Entwicklungscontainer. Ein Browser-Tab auf Ihrem Laptop nutzt dagegen den Netzwerkpfad Ihres Laptops.

Diese Unterscheidung kann Zeit sparen. Wird eine Website in Ihrem lokalen Browser nicht geladen, hat das Hinzufügen von HTTPS_PROXY zum Codespace möglicherweise keine Wirkung. Schlägt dagegen npm install im Codespace-Terminal fehl, hilft ein Proxy, der nur auf Ihrem Laptop konfiguriert ist, womöglich ebenfalls nicht.

Notieren Sie das betroffene Tool, das Ziel, das es erreichen soll, und ob die Anfrage vom Terminal, einer Editor-Erweiterung oder Ihrem lokalen Browser ausgeht. Ein Fehler bei pip install weist beispielsweise auf Datenverkehr aus dem Container hin; eine fehlgeschlagene Anmeldeseite im lokalen Browser deutet auf das lokale Netzwerk oder die Browserkonfiguration hin.

Beschränken Sie den Umfang auf das Notwendige. Den gesamten Datenverkehr über einen Proxy zu leiten, obwohl nur eine Paketregistrierung gesperrt ist, kann unnötige Probleme verursachen – insbesondere, wenn interne Dienste direkt erreichbar bleiben sollen.

2. Prüfen, was der Proxy Ihrer Organisation zulässt

Fragen Sie Ihre Netzwerkadministration nach Hostname und Port des Proxys, dem erforderlichen Protokoll und der Authentifizierungsmethode. Klären Sie außerdem, ob der Proxy einen Benutzernamen und ein Passwort, ein Client-Zertifikat oder eine im Container installierte Zertifizierungsstelle voraussetzt. Übernehmen Sie diese Angaben nicht einfach von einer Proxy-Einstellung auf einem anderen Gerät.

Erkundigen Sie sich, welche Ziele für die konkrete Aufgabe freigegeben sind. Ein Paketmanager benötigt möglicherweise Zugriff auf eine Paketregistrierung, während ein Installationsprogramm für ein Tool Dateien von einem separaten Release-Host herunterlädt. Ihre Administration kann bestätigen, welche Hostnamen zulässig sind. Notieren Sie diese, bevor Sie mit der Fehlersuche beginnen, damit Sie ein gesperrtes Ziel von einer falschen Proxy-Adresse unterscheiden können.

Prüfen Sie, ob HTTPS-Verkehr inspiziert wird. Bei einer solchen Inspektion kann der Proxy Zertifikate ausstellen, die von Ihrer Organisation signiert wurden, statt von der öffentlichen Zertifizierungsstelle, die ein Tool erwartet. Das Zertifikat Ihrer Organisation und die freigegebene Installationsanleitung erhalten Sie von der Administration – nicht aus einer Fehlermeldung kopiert.

Wenn Sie Proxy-Typen vergleichen oder den Zugriff für andere Tools einrichten, finden Sie im proxy authentication best practices Hinweise zum sicheren Umgang mit Zugangsdaten. Eine allgemeinere Entscheidung zur Netzwerkweiterleitung behandelt der Beitrag So wählen Sie ein VPN aus. VPN und Proxy werden in Codespaces nicht auf dieselbe Weise konfiguriert.

3. Proxy-Variablen für den Entwicklungscontainer konfigurieren

Viele Kommandozeilenprogramme verwenden die Umgebungsvariablen HTTP_PROXY und HTTPS_PROXY. Wenn Sie HTTP_PROXY in Codespaces einrichten, setzen Sie die Variable in der Umgebung des Entwicklungscontainers und verwenden Sie dabei das von Ihrer Administration angegebene Adressformat. Ein typischer Wert sieht etwa so aus: http://proxy.example.net:8080. Verwenden Sie jedoch das tatsächliche Protokoll, den Hostnamen und den Port Ihrer Organisation.

Setzen Sie NO_PROXY für Ziele, die den Proxy umgehen sollen, etwa freigegebene interne Dienste oder lokale Adressen. Welche Einträge genau erforderlich sind, hängt von Ihrem Netzwerk und den verwendeten Tools ab. Ein zu weit gefasster Wert kann interne Anfragen am vorgesehenen Weg vorbeileiten; ein zu eng gefasster Wert kann dazu führen, dass eine Anfrage weiterhin versucht, ein gesperrtes Ziel direkt zu erreichen.

Für einen schnellen, vorübergehenden Test können Sie die Variablen in einer Terminalsitzung setzen, bevor Sie einen Befehl ausführen. So lässt sich prüfen, ob eine Paketinstallation funktioniert. Das ist jedoch keine zuverlässige Methode, um alle Terminals oder künftigen Codespace-Sitzungen zu konfigurieren. Auch die Shell-Syntax unterscheidet sich. Fügen Sie keine Proxy-URL mit Zugangsdaten in einen Befehl ein, der möglicherweise im Shell-Verlauf gespeichert wird.

Für eine reproduzierbare Projekteinstellung hinterlegen Sie nicht geheime Werte in der für das Repository verwendeten Entwicklungscontainer-Konfiguration, etwa in einer geeigneten Dev-Container-Konfiguration oder einem Einrichtungsskript. Passwörter und Tokens gehören nicht in versionierte Dateien. Falls Sie Zugangsdaten benötigen, verwenden Sie eine von Ihrer Organisation unterstützte und freigegebene Methode zur Einbindung von Geheimnissen. Klären Sie außerdem, welche Prozesse darauf zugreifen können.

Gehen Sie nicht davon aus, dass jede Anwendung diese Variablen berücksichtigt. Manche Tools lesen kleingeschriebene Varianten, andere verwenden eigene Konfigurationsdateien und wieder andere ignorieren Umgebungsvariablen. Testen Sie den konkreten Befehl, der fehlgeschlagen ist. Dass HTTPS_PROXY gesetzt ist, beweist nicht, dass der gesamte Codespace-Datenverkehr über den Proxy läuft.

4. Proxyeinstellungen über Neuerstellungen des Codespace hinweg beibehalten

Eine Einstellung, die Sie in einem einzelnen Terminal eingeben, kann verschwinden, sobald Sie das Terminal schließen oder den Codespace neu erstellen. Damit nicht vertrauliche, für das Projekt erforderliche Einstellungen erhalten bleiben, verwenden Sie eine Konfiguration auf Repository-Ebene, die beim Erstellen des Entwicklungscontainers eingerichtet wird. Teammitglieder, die dasselbe Projekt öffnen, erhalten dann dieselbe Grundeinrichtung, ohne dass ein privates Zugangsdatengeheimnis ins Repository kopiert werden muss.

Persönliche Einstellungen sind möglicherweise besser geeignet, wenn der Proxy nur für Ihr Konto gilt oder der Wert vertraulich ist. Prüfen Sie zunächst die Codespaces-Richtlinien und verfügbaren Einstellungen Ihrer Organisation: Eine Administration kann persönliche Konfigurationen, Geheimnisse oder bestimmte Funktionen von Entwicklungscontainern einschränken.

Erstellen Sie den Codespace nach einer Konfigurationsänderung neu, wenn diese beeinflusst, wie der Container eingerichtet wird. Öffnen Sie anschließend ein neues Terminal und prüfen Sie die Variablen. Eine Neuerstellung ist ein sinnvoller Test: Verschwindet die Proxyeinstellung danach, wurde sie wahrscheinlich nur in der vorherigen Shell gesetzt und nicht in einer dauerhaften Konfigurationsquelle.

Trennen Sie gemeinsam genutzte Konfiguration von Geheimnissen. In einem Repository können die Namen der Proxy-Variablen und das erwartete Format dokumentiert werden. Ein echtes Passwort sollte jedoch über einen freigegebenen Mechanismus für Geheimnisse bereitgestellt werden. So verhindert ein routinemäßiger Commit, dass Zugangsdaten für alle sichtbar werden, die den Projektverlauf lesen können.

5. Bei Bedarf dem Zertifikat des Proxys vertrauen

Schlagen HTTPS-Anfragen mit einem Fehler bei der Zertifikatsprüfung fehl und bestätigt Ihre Organisation, dass HTTPS-Verkehr inspiziert wird, muss der Container möglicherweise der Zertifizierungsstelle Ihrer Organisation vertrauen. Lassen Sie sich das offizielle Zertifikat und die Installationsanleitung von der Administration geben. Deaktivieren Sie die Zertifikatsprüfung niemals als Behelfslösung – dadurch wird ein mögliches Abfangproblem verschleiert, statt es zu beheben.

Das Installationsverfahren hängt vom Betriebssystem und Basis-Image des Containers ab. Ein Image auf Debian-Basis, ein Alpine-Image und ein sprachspezifisches Image können Zertifikatsspeicher unterschiedlich verwalten. Klären Sie außerdem, ob das Zertifikat bereits beim Erstellen des Containers hinzugefügt werden muss, damit es nach einer Neuerstellung weiterhin verfügbar ist.

Testen Sie nach der Installation mit demselben Tool, bei dem der ursprüngliche Fehler auftrat, eine normale HTTPS-Anfrage an ein freigegebenes Ziel. Funktioniert der Browser, während ein Kommandozeilenprogramm weiterhin eine nicht vertrauenswürdige Zertifizierungsstelle meldet, verwendet das Programm möglicherweise einen eigenen Zertifikatsspeicher oder benötigt eine separate Einstellung. Fragen Sie die Administration nach der passenden Zertifikatsdatei und dem erforderlichen Format, bevor Sie die Vertrauenseinstellungen ändern.

6. Git und Entwicklungstools getrennt testen

Beginnen Sie mit einer unkritischen Anfrage an ein von Ihrer Administration freigegebenes Ziel. Testen Sie anschließend den Paketmanager oder das Tool, bei dem der Fehler auftrat. Wenn ein Befehl erfolgreich ist, bedeutet das nicht automatisch, dass Git, pip, npm und ein sprachspezifisches Installationsprogramm den Proxy alle auf dieselbe Weise verwenden.

Prüfen Sie bei Git, ob die installierte Version in Ihrer Umgebung die Proxy-Umgebungsvariablen ausliest. Falls nicht, benötigt Git möglicherweise eine eigene Proxy-Konfiguration. Tragen Sie ein Passwort nicht direkt in eine Git-Konfigurationsdatei ein, die committet oder in Protokolle kopiert werden könnte. Verwenden Sie stattdessen eine von Ihrer Organisation freigegebene Methode zur Verwaltung von Zugangsdaten.

Prüfen Sie bei Paketmanagern sowohl die Proxyeinstellung als auch die konfigurierte Paketregistrierung. Ein Paketmanager, der auf eine interne Registrierung verweist, benötigt möglicherweise nicht dasselbe externe Ziel wie ein direkter Download. Ein Tool, das ein Release-Archiv abruft, kann wiederum einen anderen Host kontaktieren. Vergleichen Sie das im Fehler genannte Ziel mit der erhaltenen Freigabeliste.

Notieren Sie, welcher Test erfolgreich war, welcher fehlschlug und welcher Hostname betroffen war. So erhält Ihre Administration konkrete Hinweise – etwa: „Git erreicht den freigegebenen Host, aber die Paketregistrierung weist die Anfrage über den Proxy zurück“ – statt einer vagen Meldung, dass Codespaces keinen Internetzugriff hat.

7. Verbindungsfehler untersuchen, ohne Zugangsdaten preiszugeben

Führen Sie einen unkritischen Verbindungstest zu einem freigegebenen Ziel durch und prüfen Sie, ob das Ergebnis auf ein Problem bei der DNS-Auflösung, eine Zeitüberschreitung, eine fehlgeschlagene Proxy-Authentifizierung, ein gesperrtes Ziel oder eine Zertifikatsprüfung hinweist. Jeder Fehlertyp legt einen anderen nächsten Schritt nahe. Eine Zeitüberschreitung ist beispielsweise nicht dasselbe wie eine abgelehnte Authentifizierung.

Prüfen Sie, ob Proxy-Hostname und Port mit den Angaben Ihrer Administration übereinstimmen, und vergewissern Sie sich, dass die Variable in derselben Terminalsitzung gesetzt ist, in der Sie den Test ausführen. Erfordert der Proxy eine Authentifizierung, können fehlende oder abgelaufene Zugangsdaten den Zugriff verhindern, obwohl die Adresse korrekt ist.

Entfernen Sie vor dem Teilen von Terminalausgaben Benutzernamen, Passwörter, Tokens und URLs mit eingebetteten Zugangsdaten. Proxy-Fehler können die vollständige Anfrageadresse enthalten, und im Shell-Verlauf können Befehle mit Geheimnissen gespeichert bleiben. Teilen Sie stattdessen den Fehlertyp, den Zielhostnamen, den Namen des Tools und den Zeitpunkt des Fehlers mit. Diese Angaben reichen dem Netzwerkteam häufig aus, um die Protokolle zu überprüfen.

Funktioniert der Proxy in einem Codespace, aber nicht in einem anderen, vergleichen Sie deren Containerkonfiguration, Betriebssystem-Image, Umgebungsvariablen und Zertifikatseinstellungen. Ändern Sie immer nur eine Sache und führen Sie danach denselben Test erneut aus. So lässt sich leichter feststellen, ob eine Variable fehlt, ein Ziel gesperrt ist oder sich die Zertifikatsspeicher unterscheiden.

Wenn Sie GitHub Codespaces Proxy konfigurieren, testen Sie die Einstellungen mit dem konkreten Tool und Ziel, das zuvor fehlgeschlagen ist, und prüfen Sie nach einer Neuerstellung, ob sie weiterhin verfügbar sind.