Pule para o conteúdoComo usar um proxy com o GitHub Codespaces em uma rede restrita
Um Codespace do GitHub executa seu contêiner de desenvolvimento em um ambiente hospedado, enquanto o navegador que o exibe funciona no seu próprio dispositivo. Essa distinção é importante: configurar um proxy dentro do contêiner pode direcionar os downloads de pacotes feitos pelo Codespace, mas não altera automaticamente a forma como o navegador local acessa os sites. Entender essa diferença é um primeiro passo para como configurar proxy no GitHub Codespaces sem confundir o tráfego do contêiner com o do dispositivo.
Se a instalação de uma dependência falhar por causa de um firewall corporativo, comece identificando qual conexão está sendo bloqueada. A resposta determina onde o proxy precisa ser configurado e o que sua organização deve liberar — especialmente em cenários de GitHub Codespaces atrás de firewall corporativo.
1. Identifique qual tráfego do Codespaces precisa do proxy
Anote a operação específica que falha. Instalar um pacote Python com pip, buscar uma dependência Node.js com npm e baixar uma ferramenta de linha de comando pelo terminal são solicitações feitas por softwares no contêiner de desenvolvimento. Já uma aba do navegador aberta no seu laptop usa a conexão de rede desse dispositivo.
Essa diferença pode poupar tempo. Se um site não carregar no navegador local, adicionar HTTPS_PROXY ao Codespace talvez não faça diferença. Se npm install falhar no terminal do Codespace, um proxy configurado apenas no laptop também pode não ajudar.
Anote a ferramenta que falha, o destino que ela tenta acessar e se a solicitação vem do terminal, de uma extensão do editor ou do navegador local. Por exemplo, uma falha em pip install aponta para o tráfego do contêiner; uma página de login que não abre no navegador local aponta para a rede local ou para a configuração do navegador.
Mantenha o escopo restrito. Direcionar todo o tráfego por um proxy quando apenas um registro de pacotes está bloqueado pode causar falhas desnecessárias, sobretudo se os serviços internos precisarem continuar acessíveis diretamente.
2. Verifique o que o proxy da sua organização permite
Peça ao administrador de rede o nome do host e a porta do proxy, o protocolo exigido e o método de autenticação. Pergunte também se o proxy exige nome de usuário e senha, um certificado de cliente ou uma autoridade certificadora instalada no contêiner. Não tente deduzir esses dados a partir de uma configuração de proxy usada em outro dispositivo.
Peça a lista de destinos permitidos para a tarefa específica. Um gerenciador de pacotes pode precisar acessar um registro, enquanto um instalador de ferramentas pode baixar arquivos de outro servidor de lançamentos. O administrador pode confirmar quais nomes de host estão liberados. Anote-os antes de começar a solucionar o problema para diferenciar um destino bloqueado de um endereço de proxy incorreto.
Verifique se a inspeção HTTPS está ativada. Nesse caso, o proxy pode apresentar certificados emitidos pela sua organização, em vez de certificados de uma autoridade certificadora pública esperada pela ferramenta. Solicite ao administrador o certificado da organização e o procedimento de instalação aprovado; não copie um certificado de uma mensagem de erro.
Se estiver comparando tipos de proxy ou configurando o acesso para outras ferramentas, o guia de boas práticas para autenticação em proxies aborda o tratamento seguro de credenciais. Para uma visão mais ampla sobre roteamento de rede, consulte como escolher uma VPN; uma VPN e um proxy não são configurados da mesma forma no Codespaces.
3. Configure as variáveis de proxy para o contêiner de desenvolvimento
Muitas ferramentas de linha de comando leem as variáveis HTTP_PROXY e HTTPS_PROXY no Codespaces. Defina-as no ambiente do contêiner de desenvolvimento do Codespace, usando o formato de endereço fornecido pelo administrador. Um valor típico tem o formato http://proxy.example.net:8080, mas use o protocolo, o nome do host e a porta definidos pela sua organização.
Defina NO_PROXY para destinos que devem ignorar o proxy, como serviços internos aprovados ou endereços locais. As entradas exatas dependem da sua rede e das ferramentas utilizadas. Um valor abrangente demais pode enviar solicitações internas por uma rota não pretendida; um valor restrito demais pode fazer com que uma solicitação tente acessar diretamente um destino bloqueado.
Para um teste rápido e temporário, você pode definir as variáveis em uma sessão do terminal antes de executar um comando. Isso ajuda a verificar se a instalação de um pacote funciona, mas não é uma forma confiável de configurar todos os terminais ou futuras sessões do Codespace. A sintaxe também varia conforme o shell; evite colar em um comando uma URL de proxy com credenciais, pois ela pode ser salva no histórico do shell.
Para configurar o projeto de forma reproduzível, inclua as definições não secretas na configuração do contêiner de desenvolvimento usada pelo repositório, como um arquivo de configuração Dev Container ou um script de inicialização apropriado. Não inclua senhas nem tokens em arquivos versionados. Se precisar de uma credencial, use um método aprovado de injeção de segredos aceito pela sua organização e confirme quais processos podem acessá-la.
Não presuma que todos os aplicativos usam essas variáveis. Algumas ferramentas leem as variantes em letras minúsculas, outras usam arquivos de configuração próprios e há as que ignoram as variáveis de ambiente. Teste o comando específico que falhou, em vez de considerar a presença de HTTPS_PROXY como prova de que todo o tráfego do Codespace passa pelo proxy.
4. Mantenha as configurações de proxy após recriar o Codespace
Uma configuração feita em um terminal pode desaparecer quando ele é fechado ou quando o Codespace é recriado. Para manter disponíveis as configurações não confidenciais exigidas pelo projeto, use uma configuração no nível do repositório, aplicada durante a criação do contêiner de desenvolvimento. Assim, quem abrir o mesmo projeto poderá receber a configuração básica sem que uma credencial privada precise ser copiada para o repositório.
As configurações pessoais podem ser mais adequadas quando o proxy se aplica apenas à sua conta ou quando o valor é confidencial. Antes de escolher essa opção, verifique as políticas do Codespaces da sua organização e as configurações disponíveis: o administrador pode restringir configurações pessoais, segredos ou o uso de determinados recursos de contêineres de desenvolvimento.
Depois de alterar a configuração, recrie o Codespace se a mudança afetar a criação do contêiner. Em seguida, abra um novo terminal e confira as variáveis. A recriação é um teste útil: se a configuração do proxy desaparecer, provavelmente ela foi adicionada apenas ao shell anterior, e não a uma fonte de configuração persistente.
Mantenha as configurações compartilhadas separadas dos segredos. O repositório pode documentar os nomes das variáveis de proxy e o formato esperado, mas uma senha real deve ser fornecida por um mecanismo de segredos aprovado. Assim, um commit rotineiro não expõe credenciais a todas as pessoas com acesso ao histórico do projeto.
5. Confie no certificado do proxy quando necessário
Se as solicitações HTTPS falharem com um erro de verificação de certificado e sua organização confirmar que há inspeção HTTPS, talvez seja necessário configurar o contêiner para confiar na autoridade certificadora da organização. Obtenha o certificado oficial e as instruções de instalação com o administrador. Nunca desative a verificação de certificados como solução alternativa; isso pode ocultar um problema de interceptação em vez de resolvê-lo.
O procedimento de instalação depende do sistema operacional e da imagem base do contêiner. Uma imagem baseada em Debian, uma baseada em Alpine e uma imagem específica de uma linguagem podem lidar com os pacotes de certificados de maneiras diferentes. Confirme também se o certificado precisa ser adicionado durante a criação do contêiner para continuar disponível após uma recriação.
Depois da instalação, teste uma solicitação HTTPS normal para um destino aprovado usando a mesma ferramenta que falhou originalmente. Se o navegador funcionar, mas um cliente de linha de comando continuar informando que o emissor não é confiável, esse cliente pode usar um repositório de certificados separado ou exigir uma configuração própria. Antes de alterar as configurações de confiança, pergunte ao administrador qual arquivo de certificado e formato o contêiner deve usar.
6. Teste o Git e as ferramentas de desenvolvimento separadamente
Comece com uma solicitação simples para um destino aprovado pelo administrador. Em seguida, teste o gerenciador de pacotes ou a ferramenta que falhou. Uma solicitação bem-sucedida em um comando não comprova que Git, pip, npm e um instalador específico de uma linguagem usam o proxy da mesma forma.
No caso do Git, verifique se a versão instalada lê as variáveis de ambiente do proxy na sua configuração. Se não ler, talvez seja necessário configurar o proxy diretamente no Git. Evite inserir uma senha em um arquivo de configuração do Git que possa ser versionado ou copiado para registros; use um método de credenciais aprovado pela organização.
Nos gerenciadores de pacotes, confira tanto a configuração do proxy quanto a do registro. Um gerenciador configurado para usar um registro interno talvez não precise acessar o mesmo destino externo de um download direto, enquanto uma ferramenta que baixa um arquivo de lançamento pode acessar outro host. Compare o destino indicado no erro com a lista de permissões recebida.
Anote qual teste passou, qual falhou e o nome do host envolvido. Esse breve registro fornece informações úteis ao administrador — por exemplo: “O Git acessa o host aprovado, mas o registro de pacotes retorna uma negativa do proxy” — em vez de um relato vago de que o Codespaces não tem acesso à internet.
7. Investigue falhas de conexão sem expor credenciais
Faça um teste simples de conectividade com um destino aprovado e verifique se o resultado aponta para uma falha de resolução DNS, um tempo limite, uma falha de autenticação no proxy, um destino negado ou um erro de validação de certificado. Cada tipo de falha sugere uma medida diferente. Um tempo limite, por exemplo, não é o mesmo que uma rejeição de autenticação.
Confira se o nome do host e a porta do proxy correspondem aos valores fornecidos pelo administrador e se a variável está definida na mesma sessão do terminal em que você executa o teste. Se o proxy exigir autenticação, uma credencial ausente ou expirada pode impedir o acesso mesmo quando o endereço está correto.
Antes de compartilhar a saída do terminal, remova nomes de usuário, senhas, tokens e URLs que contenham credenciais. Os erros do proxy podem incluir o endereço completo da solicitação, e o histórico do shell pode reter comandos com segredos. Compartilhe o tipo de erro, o nome do host de destino, a ferramenta e o horário da falha; essas informações geralmente bastam para a equipe de rede consultar os registros.
Se o proxy funcionar em um Codespace, mas não em outro, compare a configuração do contêiner, a imagem do sistema operacional, as variáveis de ambiente e a instalação dos certificados. Faça uma alteração por vez e repita o mesmo teste. Assim, fica mais fácil identificar se a causa é uma variável ausente, um destino bloqueado ou uma diferença no repositório de certificados confiáveis.