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 Enterprise Cloud. 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.

Para ajudar os usuários a encontrar seu modelo e começar a usá-lo rapidamente, compartilhe um link para a página de criação do codespace do modelo. Por exemplo, você pode fornecer esse link em um tutorial para começar a usar a estrutura. Use a opção "Compartilhar um link profundo" e selecione Início rápido para criar um link que leva os usuários a uma página em que eles podem criar rapidamente um codespace ou retomar um recente. Para saber mais, confira Como facilitar a criação rápida e a retomada de codespaces.

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 Enterprise Cloud pertencente à respectiva conta pessoal. Para saber mais, confira Como criar um codespace com base em um modelo.

As organizações podem pagar para que seus membros e colaboradores externos usem GitHub Codespaces pagos pela organização. Isso inclui codespaces criados com base em repositórios de modelos pertencentes à organização. No entanto, se um usuário publicar um codespac-e criado com base em um modelo em sua conta pessoal, a propriedade e cobrança do codespace serão transferidas para o usuário que criou o codespace. Para saber mais, confira Sobre o faturamento do GitHub Codespaces.

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 saber mais, confira Sobre LEIAMEs.

Você também pode fornecer uma breve descrição do projeto 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. No canto superior esquerdo de GitHub, selecione e clique em Codespaces para levar você à página "Seus codespaces" em github.com/codespaces.

2. Para ver a lista completa de modelos, na seção "Explorar modelos de início rápido", clique em Ver tudo.

   

3. 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 saber mais, 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 os usuários precisarem fornecer segredos pessoais, como chaves de API para executar o aplicativo no seu modelo, você poderá solicitar que eles forneçam esses segredos. Para saber mais, confira Como especificar segredos recomendados para um repositório.
• 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.