Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Aprofundamento de GitHub Codespaces

Entenda o funcionamento do GitHub Codespaces.

O GitHub Codespaces é um ambiente de desenvolvimento instantâneo e baseado na nuvem que usa um contêiner para fornecer linguagens, ferramentas e utilitários de desenvolvimento comuns. Os GitHub Codespaces também são configuráveis, o que permite criar um ambiente de desenvolvimento personalizado para o projeto. Ao configurar um ambiente de desenvolvimento personalizado para seu projeto, você pode ter uma configuração de código reproduzível para todos os usuários do seu projeto.

Criando seu codespace

Há uma série de pontos de entrada para criar um codespace.

  • Com base em um modelo do GitHub ou em qualquer repositório de modelos no GitHub.com para iniciar um novo projeto
  • Com base em um branch no repositório para um novo trabalho de recursos
  • Com base em uma solicitação de pull aberta para explorar o trabalho em andamento
  • Com base em um commit no histórico do repositório para investigar um bug em um momento específico

Você pode criar um codespace em GitHub.com, em Visual Studio Code, ou usando GitHub CLI.

Seu codespace pode ser efêmero se você tiver de fazer algum teste ou você pode retornar ao mesmo codespace para fazer um trabalho de recurso de longo prazo.

Para obter mais informações, confira "Como criar um codespace para um repositório", "Como criar um codespace com base em um modelo" e "Como abrir um codespace existente".

Observação: você pode criar mais de um codespace por repositório ou até mesmo por branch. No entanto, há limites para o número de codespaces que você pode criar e o que você pode executar ao mesmo tempo. Se você atingir o número máximo de codespaces e tentar criar outro, uma mensagem será exibida informando que você deverá remover um codespace antes de criar um novo.

O processo de criação do codespace

Quando você cria um codespace, várias etapas ocorrem em segundo plano até que o codespace fique disponível para uso.

Etapa 1: A VM e o armazenamento são atribuídos ao seu codespace

Quando você cria um codespace, um clone superficial é feito do repositório ou do repositório de modelos quando a criação do codespace é feita com base em um modelo. O repositório é clonado para uma máquina virtual do Linux dedicada e privada para você. Ter uma VM dedicada garante que você tenha todo o conjunto de recursos de computação daquela máquina disponível para você. Se necessário, isso também permite que você tenha acesso total à raiz do seu contêiner.

Etapa 2: O contêiner foi criado

Os GitHub Codespaces usam um contêiner como ambiente de desenvolvimento. Este contêiner é criado com base nas configurações que você pode definir em um arquivo devcontainer.json ou em um Dockerfile. Se você criar um codespace com base em um modelo em branco do GitHub ou em um repositório sem um arquivo devcontainer.json, os GitHub Codespaces usarão uma imagem padrão que tenha várias linguagens e runtimes disponíveis. Para obter mais informações, confira "Introdução aos contêineres de desenvolvimento". Para obter informações sobre o que a imagem padrão contém, confira o repositório devcontainers/images.

Observação: se você quiser usar ganchos do Git no seu codespace e aplicar qualquer item no diretório de modelos do Git ao codespace, configure ganchos durante a etapa 4 após a criação do contêiner.

Como o repositório é clonado na VM do host antes de o contêiner ser criado, qualquer item contido no diretório de modelos do Git não será aplicado ao seu codespace, a menos que você configure ganchos no arquivo de configuração devcontainer.json usando postCreateCommand na etapa 4. Para obter mais informações, confira "Etapa 4: Configuração pós-criação".

Etapa 3: Conectando-se ao codespace

Quando seu contêiner for criado e qualquer outra inicialização for executada, você estará conectado ao seu codespace. Você pode se conectar a ele usando:

Passo 4: Configuração de pós-criação

Depois que você estiver conectado ao codespace, a configuração automatizada poderá continuar sendo compilada com base na configuração especificada no arquivo devcontainer.json. Você poderá ver postCreateCommand e postAttachCommand serem executados.

Caso você queira usar ganchos do Git no codespace, configure os ganchos usando os scripts de ciclo de vida devcontainer.json como postCreateCommand. Para obter informações sobre os scripts de ciclo de vida, confira a especificação de contêineres de desenvolvimento no site de contêineres de desenvolvimento.

Se tiver um repositório público de dotfiles para o GitHub Codespaces, você poderá habilitá-lo para uso com novos codespaces. Quando habilitado, seus dotfiles serão clonados para o contêiner e o script de instalação será invocado. Para obter mais informações, confira "Como personalizar o GitHub Codespaces para sua conta".

Por fim, se você criou o codespace com base em um repositório, todo o histórico do repositório será copiado com um clone completo. Se você criou o codespace com base em um modelo, o histórico completo do repositório de modelos não será preservado. Nesse caso, a menos que você esteja usando o modelo em branco, você começará com um commit inicial do conteúdo do repositório de modelos.

Durante a configuração de pós-criação, você ainda poderá usar o terminal integrado e fazer edições nos seus arquivos, mas tenha cuidado para evitar quaisquer condições de corrida entre seu trabalho e os comandos que estão sendo executados.

Ciclo de vida de Codespaces

Salvando arquivos no seu codespace

Salve as alterações nos arquivos da maneira normal, dependendo do editor que você esteja usando.

Se você trabalha em codespaces no Visual Studio Code, habilite o Salvamento Automático para garantir que as alterações sejam sempre salvas.

Fechando ou interrompendo seu codespace

O codespace continuará em execução enquanto você o estiver usando, mas atingirá o tempo limite após um período de inatividade. As mudanças no arquivo feitas no editor e a saída do terminal são contadas como atividade. Portanto, o código não atingirá o tempo limite se a saída do terminal continuar. O período de tempo limite de inatividade padrão é de 30 minutos. Você pode definir uma configuração pessoal de tempo limite para codespaces criados, mas isso pode ser anulado por uma política de tempo limite da organização. Para obter mais informações, confira "Como definir o período de tempo limite para codespaces".

Se um codespace atingir o tempo limite, ele deixará de ser executado, mas você poderá reiniciá-lo na guia do navegador (se estiver usando o codespace no navegador), de dentro do VS Code ou na lista de codespaces em https://github.com/codespaces.

Para interromper o codespace, você pode

  • No navegador: na lista de codespaces em https://github.com/codespaces, clicar nas reticências ( ... ) à direita do codespace que deseja parar e clicar em Parar codespace.
  • Em VS Code: abra a Visual Studio Code Command Palette, por exemplo, pressionando Ctrl+Shift+Enter (Windows/Linux) ou Shift+Command+P (Mac), Digite Codespaces: stop e pressione Enter.
  • No cliente JetBrains, clique no botão Parar na parte superior da janela de ferramentas do GitHub Codespaces. Para obter mais informações, confira a guia "IDEs do JetBrains" de "Como parar e iniciar um codespace".
  • Em uma janela de terminal, use o comando gh codespace stop da GitHub CLI. Para obter mais informações, confira "Como usar os GitHub Codespaces com a GitHub CLI".

Se você sair do codespace sem executar o comando de interrupção (por exemplo, fechando a aba do navegador) ou se você sair do codespace em execução sem interação, o codespace e os processos em execução continuarão até o tempo limite de inatividade seja atingido.

Ao fechar ou interromper o seu codespace, todas as alterações não autorizadas são preservadas até você conectar-se ao codespace novamente.

Executando seu aplicativo

O redirecionamento de porta dá acesso a portas TCP que estão em execução no seu codespace. Por exemplo, se você estiver executando um aplicativo web na porta 4000 dentro do seu codespace, você poderá encaminhar automaticamente a porta para tornar o aplicativo acessível a partir do seu navegador.

O encaminhamento de portas determina quais portas podem ser acessadas por você a partir da máquina remota. Mesmo que você não encaminhe uma porta, esse porta ainda poderá ser acessada para outros processos em execução dentro do próprio codespace.

Diagrama que mostra como funciona o encaminhamento de porta em um codespace

Quando um aplicativo em execução dentro dos GitHub Codespaces emite uma porta para o console, os GitHub Codespaces detectam o padrão de URL do localhost e encaminham a porta automaticamente. Você pode clicar na URL no terminal ou no link na mensagem de notificação do sistema que aparece no canto inferior direito do VS Code para abrir a porta em um navegador. Por padrão, os GitHub Codespaces encaminham as portas que usam HTTP. Para obter mais informações sobre o encaminhamento de porta, confira "Como encaminhar portas no seu codespace".

Embora as portas possam ser encaminhadas automaticamente, elas não podem ser acessadas pelo público na internet. Por padrão, todas as portas são privadas, mas você pode disponibilizar manualmente uma porta para sua organização ou público, e, em seguida, compartilhar o acesso por meio de uma URL. Para obter mais informações, confira "Como compartilhar uma porta".

A execução do seu aplicativo ao chegar pela primeira vez no seu codespace pode fazer um loop de desenvolvimento rápido interno. À medida que você edita, as alterações são salvas automaticamente e ficam disponíveis na sua porta encaminhada. Para visualizar as alterações, volte para a aba do aplicativo em execução no seu navegador e atualize-as.

Enviando e fazendo push das suas alterações

O Git é instalado por padrão no codespace. Portanto, você pode confiar no fluxo de trabalho do Git existente. Você pode trabalhar com o Git no codespace por meio do terminal ou usando os recursos de controle do código-fonte do VS Code ou JetBrains.

Se você está trabalhando com um repositório existente, pode criar um codespace com base em qualquer branch, commit ou solicitação de pull no projeto ou mudar para um branch novo ou existente de dentro do codespace ativo. Como o GitHub Codespaces foi projetado para ser efêmero, você poderá usá-lo como um ambiente isolado para experimentar, verificar a solicitação de pull de um colega ou corrigir os conflitos de mesclagem.

Se você só tiver acesso de leitura em um repositório, poderá criar um codespace para o repositório, desde que possa criar forks dele. Quando você faz um commit por meio do codespace, o GitHub Codespaces cria automaticamente um fork do repositório para você ou vincula o codespace a um fork existente, caso você já tenha um para o repositório upstream.

Se você estiver trabalhando em um codespace criado com base em um modelo, o Git estará instalado por padrão, mas você precisará publicar o codespace em um repositório remoto para persistir o trabalho e compartilhá-lo com outras pessoas. Se você começar com o modelo em branco do GitHub, primeiro, precisará inicializar o workspace como um repositório Git (por exemplo, inserindo git init) para começar a usar o controle do código-fonte no codespace.

Para obter mais informações, confira "Como usar o controle do código-fonte no seu codespace".

Observação: os commits do codespace serão atribuídos ao nome e ao email público configurados em https://github.com/settings/profile. Um token com escopo no repositório, incluído no ambiente como GITHUB_TOKEN, e as suas credenciais do GitHub serão usadas para realizar a autenticação.

Como personalizar o codespace com extensões ou plug-ins

Você pode adicionar plug-ins e extensões em um codespace para personalizar sua experiência no JetBrains e no VS Code respectivamente.

Extensões do VS Code

Se você trabalhar nos codespaces no aplicativo da área de trabalho do VS Code ou no cliente Web, poderá adicionar todas as extensões necessárias do Visual Studio Code Marketplace. Para obter informações de como as extensões são executadas nos GitHub Codespaces, confira Suporte ao desenvolvimento remoto e ao GitHub Codespaces na documentação do VS Code.

Se você já usa o VS Code, use a Sincronização de Configurações para sincronizar automaticamente extensões, configurações, temas e atalhos de teclado entre a instância local e os codespaces que você criar.

Plug-ins do JetBrains

Se você trabalhar nos codespaces em um IDE do JetBrains, poderá adicionar plug-ins do JetBrains Marketplace.

  1. Clique em Cliente JetBrains e depois em Preferências.

  2. Na caixa de diálogo Preferências, clique em Plug-ins no Host para instalar um plug-in no IDE completo do JetBrains que está sendo executado remotamente ou em Plug-ins para instalar um plug-in no cliente local, por exemplo, para alterar o tema da interface do usuário.

  3. Clique na guia Marketplace.

    Captura de tela da guia Marketplace para 'Plug-ins no Host'

  4. Clique em Instalar ao lado do plug-in necessário.

Leitura adicional