Salta al contenutoCome usare un proxy con GitHub Codespaces su una rete con restrizioni
Un Codespace di GitHub esegue il proprio container di sviluppo in un ambiente ospitato, mentre il browser che lo visualizza funziona sul tuo dispositivo. Questa distinzione è importante: configurare un proxy all’interno del container può instradare i download dei pacchetti dal Codespace, ma non cambia automaticamente il modo in cui il browser locale raggiunge i siti web. Se cerchi come configurare un proxy in GitHub Codespaces, inizia identificando quale ambiente deve usare il proxy.
Se l’installazione di una dipendenza non riesce dietro il firewall aziendale, per prima cosa individua quale connessione è bloccata. La risposta ti dirà dove configurare il proxy e quali autorizzazioni deve concedere la tua organizzazione.
1. Individua il traffico di Codespaces che deve passare dal proxy
Annota l’operazione specifica che non riesce. Installare un pacchetto Python con pip, scaricare una dipendenza Node.js con npm e scaricare uno strumento da riga di comando nel terminale sono richieste inviate da software in esecuzione nel container di sviluppo. Una scheda aperta nel browser del tuo portatile, invece, usa la connessione di rete del portatile.
Capire questa differenza può farti risparmiare tempo. Se un sito web non si carica nel browser locale, aggiungere HTTPS_PROXY al Codespace potrebbe non servire a nulla. Se npm install non riesce nel terminale del Codespace, un proxy configurato solo sul portatile potrebbe non essere d’aiuto.
Annota lo strumento che non funziona, la destinazione che cerca di raggiungere e se la richiesta proviene dal terminale, da un’estensione dell’editor o dal browser locale. Per esempio, un errore di pip install indica un problema con il traffico del container; una pagina di accesso che non si apre nel browser locale indica un problema della rete locale o della configurazione del browser.
Limita l’ambito della configurazione. Instradare tutto il traffico attraverso un proxy quando è bloccato un solo registro di pacchetti può causare problemi inutili, soprattutto se i servizi interni devono restare raggiungibili direttamente.
2. Verifica quali destinazioni sono consentite dal proxy aziendale
Chiedi all’amministratore di rete il nome host e la porta del proxy, il protocollo richiesto e il metodo di autenticazione. Chiedi anche se il proxy richiede nome utente e password, un certificato client o una CA da installare nel container. Non dedurre questi dettagli dalle impostazioni proxy usate su un altro dispositivo.
Chiedi quali destinazioni sono consentite per l’attività specifica. Un gestore di pacchetti potrebbe dover accedere a un registro, mentre un programma di installazione potrebbe scaricare file da un host di release distinto. L’amministratore può confermare quali nomi host sono consentiti: annotali prima di iniziare la diagnosi, così potrai distinguere una destinazione bloccata da un indirizzo proxy errato.
Verifica se è attiva l’ispezione HTTPS. In tal caso, il proxy potrebbe presentare certificati emessi dalla tua organizzazione anziché da una CA pubblica attesa dallo strumento. Chiedi all’amministratore il certificato dell’organizzazione e la procedura approvata per installarlo; non usare un certificato copiato da un messaggio di errore.
Se stai confrontando i tipi di proxy o configurando l’accesso per altri strumenti, la guida alle best practice per l’autenticazione proxy spiega come gestire le credenziali in sicurezza. Per una panoramica più ampia sull’instradamento del traffico, consulta come scegliere una VPN: VPN e proxy non si configurano allo stesso modo in Codespaces.
3. Configura le variabili proxy per il container di sviluppo
Molti strumenti da riga di comando leggono le variabili d’ambiente HTTP_PROXY e HTTPS_PROXY. Impostare le variabili HTTP_PROXY e HTTPS_PROXY in Codespaces può consentire a questi strumenti di usare il proxy aziendale; inserisci i valori nell’ambiente del container di sviluppo, usando il formato dell’indirizzo fornito dall’amministratore. Un valore tipico ha questo formato: http://proxy.example.net:8080. Usa però il protocollo, il nome host e la porta effettivi della tua organizzazione.
Imposta NO_PROXY per le destinazioni che devono aggirare il proxy, ad esempio i servizi interni autorizzati o gli indirizzi locali. Le voci esatte dipendono dalla rete e dagli strumenti utilizzati. Un valore troppo ampio può instradare le richieste interne su un percorso non previsto; uno troppo ristretto può lasciare che una richiesta tenti di raggiungere direttamente una destinazione bloccata.
Per una prova rapida e temporanea, puoi impostare le variabili in una sessione del terminale prima di eseguire un comando. È utile per verificare se l’installazione di un pacchetto funziona, ma non è un metodo affidabile per configurare tutti i terminali o le sessioni future del Codespace. Anche la sintassi varia in base alla shell: non incollare un URL proxy contenente credenziali in un comando che potrebbe essere salvato nella cronologia della shell.
Per configurare il progetto in modo ripetibile, inserisci le impostazioni non riservate nella configurazione del container di sviluppo usata dal repository, ad esempio in un file di configurazione Dev Container adatto o in uno script di setup. Non inserire password o token nei file versionati. Se ti serve una credenziale, usa un metodo approvato per iniettare segreti e verifica quali processi possono leggerla.
Non dare per scontato che tutte le applicazioni rispettino queste variabili. Alcuni strumenti leggono le varianti in minuscolo, altri usano file di configurazione propri e altri ancora ignorano le variabili d’ambiente. Verifica il comando specifico che non funzionava: la semplice presenza di HTTPS_PROXY non dimostra che tutto il traffico del Codespace passi dal proxy.
4. Mantieni le impostazioni proxy dopo la ricreazione del Codespace
Un’impostazione inserita in un terminale può scomparire alla chiusura del terminale o quando il Codespace viene ricreato. Per mantenere disponibili le impostazioni non riservate richieste dal progetto, usa una configurazione a livello di repository applicata durante la creazione del container di sviluppo. In questo modo, chi apre lo stesso progetto può ottenere la configurazione di base senza dover copiare credenziali private nel repository.
Le impostazioni personali possono essere più adatte se il proxy si applica solo al tuo account o se il valore è sensibile. Prima di scegliere questa soluzione, verifica le policy di Codespaces della tua organizzazione e le impostazioni disponibili: l’amministratore potrebbe limitare la configurazione personale, i segreti o l’uso di determinate funzionalità dei container di sviluppo.
Dopo aver modificato la configurazione, ricrea il Codespace se la modifica riguarda la creazione del container, quindi apri un nuovo terminale e verifica le variabili. La ricreazione è una prova utile: se l’impostazione proxy scompare, probabilmente era stata aggiunta solo alla shell precedente e non a una configurazione persistente.
Tieni separate le impostazioni condivise dai segreti. Il repository può documentare i nomi delle variabili proxy e il formato previsto, ma una password reale deve essere fornita tramite un meccanismo approvato per la gestione dei segreti. Così eviti che un normale commit esponga le credenziali a chiunque possa leggere la cronologia del progetto.
5. Considera attendibile il certificato del proxy, se necessario
Se le richieste HTTPS falliscono con un errore di verifica del certificato e la tua organizzazione conferma che è attiva l’ispezione HTTPS, potrebbe essere necessario configurare il container affinché consideri attendibile la CA aziendale. Procurati il certificato ufficiale e le istruzioni per installarlo dall’amministratore. Non disattivare la verifica dei certificati come soluzione temporanea: potresti nascondere un problema di intercettazione invece di risolverlo.
La procedura di installazione dipende dal sistema operativo e dall’immagine di base del container. Un’immagine basata su Debian, una basata su Alpine e un’immagine specifica per un linguaggio possono gestire i bundle di certificati in modo diverso. Verifica anche se il certificato va aggiunto durante la creazione del container, affinché resti disponibile dopo una ricreazione.
Dopo averlo installato, prova una normale richiesta HTTPS verso una destinazione autorizzata, usando lo stesso strumento che aveva segnalato l’errore. Se il browser funziona ma un client da riga di comando continua a segnalare un emittente non attendibile, potrebbe usare un archivio certificati separato o richiedere un’impostazione propria. Prima di modificare la configurazione dei certificati attendibili, chiedi all’amministratore quale file e formato usare nel container.
6. Verifica Git e gli strumenti di sviluppo separatamente
Inizia con una richiesta innocua verso una destinazione autorizzata dall’amministratore. Poi prova il gestore di pacchetti o lo strumento che non funzionava. Il fatto che una richiesta riesca non dimostra che Git, pip, npm e un programma di installazione specifico di un linguaggio usino tutti il proxy allo stesso modo.
Per Git, verifica se la versione installata legge le variabili d’ambiente del proxy nella tua configurazione. In caso contrario, potrebbe essere necessario configurare il proxy direttamente in Git. Evita di inserire una password in chiaro in un file di configurazione Git che potrebbe essere incluso in un commit o copiato nei log; usa invece un metodo di gestione delle credenziali approvato dall’organizzazione.
Per i gestori di pacchetti, controlla sia l’impostazione del proxy sia il registro configurato. Un gestore di pacchetti diretto a un registro interno potrebbe non aver bisogno della stessa destinazione esterna usata per un download diretto, mentre uno strumento che scarica un archivio di release potrebbe contattare un host completamente diverso. Confronta la destinazione indicata nell’errore con l’elenco di host autorizzati che hai ricevuto.
Se devi risolvere errori npm e pip dietro un proxy aziendale, controlla separatamente le impostazioni del proxy, il registro o l’indice configurato e l’eventuale certificato richiesto. Confronta poi la destinazione indicata nell’errore con l’elenco di host autorizzati dall’amministratore.
Annota quali prove sono riuscite, quali sono fallite e il nome host coinvolto. Così potrai fornire all’amministratore informazioni utili — ad esempio: «Git raggiunge l’host autorizzato, ma il registro dei pacchetti rifiuta la richiesta tramite proxy» — invece di limitarti a dire che Codespaces non ha accesso a Internet.
7. Diagnostica i problemi di connessione senza esporre le credenziali
Esegui una prova di connettività innocua verso una destinazione autorizzata e controlla se il risultato indica un errore di risoluzione DNS, un timeout, un problema di autenticazione proxy, una destinazione negata o un errore di convalida del certificato. Ogni tipo di errore suggerisce un passo successivo diverso. Un timeout, per esempio, non equivale a un rifiuto dell’autenticazione.
Controlla che il nome host e la porta del proxy corrispondano ai valori forniti dall’amministratore e verifica che la variabile sia presente nella stessa sessione del terminale da cui esegui il test. Se il proxy richiede l’autenticazione, una credenziale mancante o scaduta può impedire l’accesso anche se l’indirizzo è corretto.
Prima di condividere l’output del terminale, rimuovi nomi utente, password, token e URL contenenti credenziali. Gli errori del proxy possono includere l’indirizzo completo della richiesta e la cronologia della shell può conservare i comandi che contengono segreti. Condividi invece il tipo di errore, il nome host di destinazione, lo strumento utilizzato e l’ora in cui si è verificato: spesso bastano queste informazioni perché il team di rete possa controllare i log.
Se il proxy funziona in un Codespace ma non in un altro, confronta la configurazione dei container, le immagini dei sistemi operativi, le variabili d’ambiente e l’impostazione dei certificati. Modifica una sola cosa alla volta e ripeti la stessa prova. Sarà più facile capire se il problema dipende da una variabile mancante, da una destinazione bloccata o da una differenza nell’archivio dei certificati attendibili.