Como configurar um repositório de modelos para os GitHub Codespaces

Introdução

Ao configurar um repositório de modelos, você pode ajudar as pessoas a começar a usar a estrutura, a biblioteca ou outro projeto nos GitHub Codespaces. Os usuários poderão começar a trabalhar com os arquivos de modelo imediatamente em um ambiente de desenvolvimento baseado em nuvem, sem precisar se preocupar em clonar o repositório ou instalar ferramentas ou outras dependências. Com alguma configuração, você poderá configurar usuários em um codespace com arquivos importantes já abertos para edição e com um aplicativo já em execução em uma guia de navegador de visualização dentro do editor da Web do VS Code.

Qualquer pessoa com acesso de leitura ao repositório de modelos pode criar um codespace na página do repositório no GitHub. Você pode transformar qualquer repositório existente em um modelo e não precisa alterar nenhuma configuração para permitir que os usuários criem um codespace usando o repositório de modelos. Para obter mais informações sobre como transformar um repositório em um modelo, confira "Criar um repositório de modelos".

Você pode fornecer um link no formato https://github.com/codespaces/new?template_repository=OWNER/TEMPLATE-REPO para levar os usuários diretamente a uma página "Criar um codespace" do modelo.

Por exemplo, você pode fornecer esse link em um tutorial para começar a usar a estrutura. No link, substitua OWNER/TEMPLATE-REPO pelo nome do repositório de modelos, por exemplo monalisa/octo-template.

Quando alguém cria um codespace usando o modelo, o conteúdo do repositório de modelos é clonado no codespace da pessoa. Quando o usuário estiver pronto, ele poderá publicar o trabalho em um novo repositório em GitHub pertencente à respectiva conta pessoal. Todos os encargos de uso do codespace serão cobrados do usuário que o criou. Para obter mais informações, confira "Como criar um codespace com base em um modelo".

Descrever o modelo

Se você não tiver um LEIAME do repositório de modelos, crie-o para descrever a finalidade do modelo e como começar a usá-lo. Para obter mais informações, confira "Sobre LEIAMEs".

Uma breve descrição do modelo é exibida na página "Criar um codespace" na qual os usuários entram ao clicar no link https://github.com/codespaces/new?template_repository=OWNER/TEMPLATE-REPO. Essa descrição é obtida do campo Descrição que você pode definir ao criar um repositório. Você pode editar essa descrição a qualquer momento navegando até a página do repositório e clicando em ao lado da seção Sobre à direita da página.

Adicionar arquivos iniciais

Os repositórios de modelo normalmente contêm arquivos iniciais com código clichê para que os usuários possam começar rapidamente a usar uma biblioteca, estrutura ou outra tecnologia.

Para obter diretrizes sobre os tipos de arquivos a serem incluídos, examine os arquivos iniciais incluídos nos modelos oficiais do GitHub para GitHub Codespaces, da maneira a seguir.

1. Navegue até a página "Seus codespaces" em github.com/codespaces. 1. Para ver a lista completa de modelos, na seção "Explorar modelos de início rápido", clique em Ver tudo.

   

2. Para exibir o repositório de modelos que contém os arquivos do modelo, clique no nome do modelo.

   

Configurar o contêiner de desenvolvimento

Você pode adicionar arquivos de configuração de contêiner de desenvolvimento ao repositório de modelos para personalizar o ambiente de desenvolvimento para pessoas que usam o modelo com GitHub Codespaces. Você pode escolher uma opção em uma lista de configurações predefinidas no Visual Studio Code ou criar uma configuração personalizada escrevendo o próprio arquivo devcontainer.json. Se você não adicionar arquivos de configuração, a imagem de contêiner padrão será usada. Para obter mais informações, confira "Introdução aos contêineres de desenvolvimento" e "Adicionando uma configuração de contêiner de desenvolvimento ao repositório."

Você deve configurar o contêiner de desenvolvimento com as ferramentas e a personalização necessária para oferecer aos usuários a melhor experiência possível com o modelo. Por exemplo, no arquivo devcontainer.json:

• Você pode usar a propriedade openFiles para definir uma lista de arquivos a serem abertos automaticamente no cliente Web VS Code quando um codespace é criado com base em um modelo.
• Se o modelo contiver arquivos para um aplicativo Web, você poderá fazer com que o aplicativo seja executado automaticamente no codespace do usuário. Você pode fazer isso usando a propriedade postAttachCommand para executar um script que inicia o aplicativo em um servidor local assim que o cliente Web VS Code se conecta ao codespace e definindo a propriedade onAutoForward de uma porta como openPreview para exibir o aplicativo em execução nessa porta em um navegador simples inserido no cliente Web VS Code.

As definições de configurações a seguir para um modelo React abrirão o arquivo app.js no editor do usuário, executarão npm start (definido em um arquivo package.json) para iniciar um servidor local e encaminharão a porta 3000 a uma guia de navegador de visualização no codespace.

{
    "postAttachCommand": {
      "server": "npm start"
    },

    "portsAttributes": {
      "3000": {
        "label": "Application",
        "onAutoForward": "openPreview"
      }
    },

    "customizations": {
      "codespaces": {
        "openFiles": ["src/App.js"]
      }
    }
}

Para saber mais, confira "Abrir arquivos automaticamente nos codespaces de um repositório" e a especificação de contêineres de desenvolvimento no site de contêineres de desenvolvimento.