Aprofundamento de 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, uma máquina virtual (VM) é criada usando a versão estável ou beta da imagem do host da VM. Para obter mais informações, confira "Escolher a imagem do host estável ou beta". A imagem do host define a versão do Linux usada para a VM. A VM é 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.

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. A clonagem é feita no diretório /workspaces da VM e, posteriormente, montada no contêiner de desenvolvimento. Para obter mais informações, confira "Sobre a estrutura de diretório de um codespace" abaixo.

Etapa 2: contêiner de desenvolvimento criado

O GitHub Codespaces usa um contêiner do Docker 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 detalhes sobre o que a imagem padrão de contêineres de desenvolvimento inclui, 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 seu período de tempo limite para o GitHub 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.
No VS Code: abra a Visual Studio Code Command Palette, por exemplo, pressionando Ctrl+Shift+P (Windows/Linux) ou Shift+Command+P (Mac) - digite Codespaces: stop e pressione Enter. Para obter mais informações, confira "Uso da paleta de comandos do Visual Studio Code no GitHub Codespaces".
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 do "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 o GitHub Codespaces com a CLI do GitHub".

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 mostrando conexões, pela Internet, entre um editor de código ou um navegador em seu dispositivo e um codespace na nuvem.

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 "Encaminhar portas no seu código".

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 "Encaminhar portas no seu código".

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 ou efetua push de um novo branch, o GitHub Codespaces cria automaticamente um fork do repositório para você ou, caso você já tenha um fork para o repositório upstream, vincula o codespace a ele.

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 "Usando controle de origem 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.

Clique em Cliente JetBrains e depois em Preferências.
No diálogo Preferências, clique em Plug-ins do 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.
Clique na guia Marketplace.
Clique em Instalar ao lado do plug-in necessário.

Sobre a estrutura de diretório de um codespace

Quando você cria um codespace, seu repositório é clonado no diretório /workspaces no seu codespace. Esse é um diretório persistente que é montado no contêiner. Todas as alterações feitas dentro desse diretório, incluindo edição, adição ou exclusão de arquivos, são preservadas quando você para e inicia o codespace e recompila o contêiner no codespace.

Fora do diretório /workspaces, o codespace contém uma estrutura de diretório do Linux que varia conforme a imagem de contêiner de desenvolvimento usada para criar o codespace. Você pode adicionar arquivos ou fazer alterações em arquivos fora do diretório /workspaces: por exemplo, você pode instalar novos programas ou definir sua configuração de shell em um arquivo como ~/.bashrc. Como um usuário não raiz, talvez você não tenha acesso de gravação automaticamente em alguns diretórios, mas a maioria das imagens permite o acesso raiz a esses diretórios com o comando sudo.

Fora de /workspaces, com exceção do diretório /tmp, os diretórios em um codespace são vinculados ao ciclo de vida do contêiner. Isso significa que todas as alterações feitas são preservadas quando você para e inicia o codespace, mas não são preservadas quando você recompila o contêiner. Para obter mais informações sobre o diretório /tmp, confira "Variáveis de ambiente persistentes e arquivos temporários".

A limpeza dos diretórios fora de /workspaces ajuda a garantir que o contêiner recompilado esteja no mesmo estado que estaria em um codespace recém-criado. Se você estiver recompilando um contêiner para aplicar alterações de configuração ao codespace no qual está trabalhando, tenha certeza de que todas as alterações de configuração feitas funcionarão da mesma forma para os usuários que criam codespaces com a mesma configuração. Para obter mais informações, confira "Introdução aos contêineres de desenvolvimento".

Caso você deseje fazer alterações no seu codespace que serão mais robustas em recompilações e em diferentes codespaces, há várias opções.

Para instalar programas e ferramentas em todos os codespaces criados com base em um repositório, na configuração do contêiner de desenvolvimento, você pode usar propriedades de comando do ciclo de vida, como postCreateCommand para executar comandos de instalação personalizados ou escolher um dos comandos de instalação escritos previamente chamados "recursos". Para saber mais, confira a especificação de contêineres de desenvolvimento no site Contêineres de desenvolvimento e "Como adicionar recursos a um arquivo devcontainer.json".
Para instalar ferramentas ou personalizar sua configuração em cada codespace criado, como configurar seu perfil bash, vincule o GitHub Codespaces a um repositório de dotfiles. O repositório de dotfiles também é clonado no diretório persistente /workspaces. Para obter mais informações, confira "Como personalizar o GitHub Codespaces para sua conta".
Caso você deseje preservar arquivos específicos em uma recompilação, use um arquivo devcontainer.json para criar um link simbólico entre os arquivos e um diretório persistente dentro de /workspaces. Para obter mais informações, confira "Como recompilar o contêiner em um codespace".