Saltar al contenidoCómo usar un proxy con GitHub Codespaces en una red restringida
GitHub Codespaces ejecuta el contenedor de desarrollo en un entorno alojado, mientras que el navegador que lo muestra se ejecuta en tu propio dispositivo. Esta diferencia es importante: configurar un proxy dentro del contenedor puede dirigir las descargas de paquetes desde el Codespace, pero no cambia automáticamente la forma en que tu navegador local se conecta a los sitios web. Si necesitas saber cómo configurar un proxy en GitHub Codespaces, empieza por identificar qué tráfico debe pasar por él.
Si falla la instalación de una dependencia detrás del firewall de la empresa, averigua primero qué conexión está bloqueada. La respuesta determinará dónde debes configurar el proxy y qué debe permitir tu organización.
1. Identifica qué tráfico de Codespaces necesita el proxy
Anota la operación concreta que falla. Instalar un paquete de Python con pip, descargar una dependencia de Node.js con npm y descargar una herramienta de línea de comandos desde una terminal son solicitudes que realiza el software del contenedor de desarrollo. En cambio, una pestaña abierta en el navegador de tu portátil utiliza la conexión de red de ese dispositivo.
Tener clara esta diferencia puede ahorrarte tiempo. Si un sitio web no carga en tu navegador local, añadir HTTPS_PROXY al Codespace quizá no sirva de nada. Y si falla npm install en la terminal del Codespace, configurar un proxy solo en tu portátil tampoco necesariamente ayudará.
Anota qué herramienta falla, a qué destino intenta conectarse y si la solicitud procede de la terminal, de una extensión del editor o del navegador local. Por ejemplo, un error de pip install apunta al tráfico del contenedor; si no carga una página de inicio de sesión en el navegador local, el problema apunta a la red local o a la configuración del navegador.
Limita el alcance. Dirigir todo el tráfico a través de un proxy cuando solo está bloqueado un registro de paquetes puede provocar problemas innecesarios, sobre todo si los servicios internos deben seguir siendo accesibles directamente. Si tu objetivo es usar GitHub Codespaces detrás de un firewall, determina primero qué destinos y herramientas necesitan acceso.
2. Comprueba qué permite el proxy de tu organización
Pide al administrador de red el nombre de host y el puerto del proxy, el protocolo requerido y el método de autenticación. Pregunta también si el proxy requiere nombre de usuario y contraseña, un certificado de cliente o una autoridad certificadora instalada en el contenedor. No des por sentado que los datos de configuración de otro dispositivo también son válidos.
Pregunta qué destinos están permitidos para la tarea específica. Un gestor de paquetes puede necesitar acceso a un registro, mientras que una herramienta de instalación quizá descargue archivos desde otro servidor. El administrador puede confirmar qué nombres de host están autorizados. Anótalos antes de empezar a solucionar el problema para distinguir un destino bloqueado de una dirección de proxy incorrecta.
Comprueba si está habilitada la inspección de HTTPS. En ese caso, el proxy puede presentar certificados emitidos por tu organización, en lugar de certificados de una autoridad certificadora pública que la herramienta espera. El administrador debe proporcionarte el certificado de la organización y las instrucciones aprobadas para instalarlo; no uses uno copiado de un mensaje de error.
Si estás comparando tipos de proxy o configurando el acceso para otras herramientas, consulta la guía de buenas prácticas para la autenticación de proxies, que explica cómo proteger las credenciales. Para tomar una decisión más amplia sobre el enrutamiento de red, consulta cómo elegir una VPN; una VPN y un proxy no se configuran de la misma manera en Codespaces.
3. Configura las variables de proxy para el contenedor de desarrollo
Muchas herramientas de línea de comandos leen las variables HTTP_PROXY y HTTPS_PROXY en Codespaces, disponibles como variables de entorno HTTP_PROXY y HTTPS_PROXY. Configúralas en el entorno del contenedor de desarrollo del Codespace y utiliza el formato de dirección que te haya indicado el administrador. Un valor típico tiene el formato http://proxy.example.net:8080, pero debes usar el protocolo, el nombre de host y el puerto reales de tu organización.
Define NO_PROXY para los destinos que deban omitir el proxy, como los servicios internos autorizados o las direcciones locales. Las entradas exactas dependerán de la red y de las herramientas que utilices. Un valor demasiado amplio puede enviar solicitudes internas por una ruta no prevista; uno demasiado restrictivo puede hacer que una solicitud intente conectarse directamente a un destino bloqueado.
Para hacer una prueba rápida y temporal, puedes definir las variables en una sesión de terminal antes de ejecutar un comando. Esto sirve para comprobar si funciona la instalación de un paquete, pero no es una forma fiable de configurar todas las terminales ni las futuras sesiones de Codespaces. La sintaxis también varía según el shell; no pegues en un comando una URL de proxy con credenciales si puede quedar guardada en el historial del shell.
Para que la configuración del proyecto sea reproducible, incluye los ajustes no confidenciales en la configuración del contenedor de desarrollo que utiliza el repositorio, como un archivo de configuración de Dev Container o un script de instalación adecuado. No guardes contraseñas ni tokens en archivos versionados. Si necesitas credenciales, utiliza un método aprobado de inyección de secretos que admita tu organización y confirma qué procesos pueden acceder a ellas.
No des por sentado que todas las aplicaciones utilizan estas variables. Algunas herramientas leen las variantes en minúsculas, otras tienen sus propios archivos de configuración y algunas ignoran las variables de entorno. Prueba el comando concreto que falló; que exista HTTPS_PROXY no demuestra que todo el tráfico del Codespace esté pasando por el proxy.
4. Haz que la configuración del proxy persista al reconstruir el Codespace
Una configuración introducida en una terminal puede desaparecer al cerrar esa terminal o reconstruir el Codespace. Para que los ajustes no confidenciales que necesita el proyecto sigan disponibles, utiliza una configuración del repositorio que se aplique al crear el contenedor de desarrollo. Así, quienes abran el mismo proyecto tendrán la misma configuración básica, sin necesidad de copiar credenciales privadas al repositorio.
Si el proxy solo se aplica a tu cuenta o el valor es confidencial, quizá sea más adecuado usar una configuración personal. Antes de elegir esta opción, consulta las políticas de Codespaces y los ajustes disponibles en tu organización: el administrador puede restringir la configuración personal, el uso de secretos o determinadas funciones de los contenedores de desarrollo.
Después de cambiar la configuración, reconstruye el Codespace si el cambio afecta a la creación del contenedor. Luego abre una terminal nueva y comprueba las variables. La reconstrucción sirve como prueba: si la configuración del proxy desaparece, probablemente solo se había añadido al shell anterior y no a una fuente de configuración persistente.
Mantén separada la configuración compartida de los secretos. El repositorio puede documentar los nombres de las variables del proxy y el formato esperado, pero la contraseña real debe proporcionarse mediante un mecanismo de secretos aprobado. Así, un commit rutinario no expondrá las credenciales a todas las personas con acceso al historial del proyecto.
5. Confía en el certificado del proxy cuando sea necesario
Si las solicitudes HTTPS fallan con un error de verificación del certificado y tu organización confirma que inspecciona el tráfico HTTPS, quizá debas configurar el contenedor para que confíe en la autoridad certificadora de la organización. Pide al administrador el certificado oficial y las instrucciones de instalación. No desactives las comprobaciones de certificados como solución provisional: podrías ocultar un problema de interceptación en lugar de resolverlo.
El procedimiento de instalación depende del sistema operativo y de la imagen base del contenedor. Una imagen basada en Debian, otra basada en Alpine y una imagen específica de un lenguaje pueden gestionar de forma distinta los paquetes de certificados. Confirma también si debes añadir el certificado durante la creación del contenedor para que siga disponible después de una reconstrucción.
Una vez instalado, prueba una solicitud HTTPS normal a un destino autorizado con la misma herramienta que falló inicialmente. Si el navegador funciona, pero un cliente de línea de comandos sigue indicando que el emisor no es de confianza, puede que ese cliente utilice otro almacén de certificados o requiera una configuración propia. Antes de modificar la configuración de confianza, pregunta al administrador qué archivo de certificado y qué formato debe usar el contenedor.
6. Prueba Git y las herramientas de desarrollo por separado
Empieza con una solicitud inocua a un destino autorizado por el administrador. Después prueba el gestor de paquetes o la herramienta que falló. Que una solicitud funcione con un comando no demuestra que Git, pip, npm y un instalador específico de un lenguaje gestionen el proxy de la misma forma.
En el caso de Git, comprueba si la versión instalada lee las variables de entorno del proxy en tu configuración. Si no es así, puede que Git necesite una configuración de proxy propia. No incluyas una contraseña directamente en un archivo de configuración de Git que podría subirse al repositorio o copiarse en los registros. Utiliza, en su lugar, un método de gestión de credenciales aprobado por tu organización.
En los gestores de paquetes, comprueba tanto la configuración del proxy como la del registro. Si el gestor apunta a un registro interno, quizá no necesite acceder al mismo destino externo que una descarga directa. Por otro lado, una herramienta que descarga un archivo de una versión puede conectarse a otro servidor. Compara el destino indicado en el error con la lista de permitidos que te dieron.
Anota qué prueba funcionó, cuál falló y qué nombre de host estaba implicado. Ese breve registro le da al administrador información útil —por ejemplo, «Git llega al host autorizado, pero el registro de paquetes devuelve una denegación del proxy»— en vez de un informe impreciso de que Codespaces no tiene internet.
7. Diagnostica los fallos de conexión sin exponer credenciales
Haz una prueba de conectividad inocua contra un destino autorizado y comprueba si el resultado apunta a un problema de resolución DNS, un tiempo de espera agotado, un error de autenticación del proxy, un destino denegado o un fallo al validar el certificado. Cada tipo de error sugiere un paso distinto. Por ejemplo, un tiempo de espera agotado no es lo mismo que un rechazo de autenticación.
Comprueba que el nombre de host y el puerto del proxy coincidan con los datos del administrador, y confirma que la variable esté definida en la misma sesión de terminal desde la que ejecutas la prueba. Si el proxy requiere autenticación, una credencial ausente o caducada puede impedir el acceso aunque la dirección sea correcta.
Antes de compartir la salida de la terminal, elimina nombres de usuario, contraseñas, tokens y URL que incluyan credenciales. Los errores del proxy pueden mostrar la dirección completa de la solicitud, y el historial del shell puede conservar comandos que contengan secretos. Comparte el tipo de error, el nombre de host de destino, la herramienta y la hora del fallo; esos datos suelen bastar para que el equipo de soporte de red revise los registros.
Si el proxy funciona en un Codespace, pero no en otro, compara la configuración del contenedor, la imagen del sistema operativo, las variables de entorno y los certificados. Cambia una sola cosa cada vez y repite la misma prueba. Así será más fácil determinar si la causa es una variable ausente, un destino bloqueado o una diferencia en el almacén de certificados de confianza.