Como restringir a imagem base dos codespaces

Visão geral

Quando você cria um codespace, um contêiner do Docker é criado automaticamente em uma máquina virtual remota. O contêiner do Docker é criado com base em uma imagem do Docker. A imagem é efetivamente um modelo para contêineres do Docker e determina muitos aspectos do ambiente resultante fornecido pelo codespace. Para saber mais, confira Visão geral do GitHub Codespaces.

Você pode escolher qual imagem deseja usar para seus codespaces especificando-a na configuração de contêiner de desenvolvimento para um repositório. Você pode fazer isso, por exemplo, usando a propriedade image no arquivo devcontainer.json.

"image": "mcr.microsoft.com/devcontainers/javascript-node:18",

"image": "mcr.microsoft.com/devcontainers/javascript-node:18",

Para saber mais, confira a especificação sobre contêineres de desenvolvimento no site de Contêineres de Desenvolvimento.

Como alternativa, você pode especificar a imagem base em um Dockerfile. Para saber mais, confira Introdução aos contêineres de desenvolvimento.

Se você não especificar uma imagem na configuração de contêiner de desenvolvimento para um repositório, a imagem padrão será usada. A imagem padrão contém várias versões de runtime para linguagens populares e ferramentas comumente usadas. Para saber mais, confira Introdução aos contêineres de desenvolvimento.

Como proprietário de uma organização, você pode adicionar uma política para restringir quais imagens podem ser usadas para codespaces criados em sua organização.

Se você tentar criar um codespace usando um devcontainer.json que especifica uma imagem não permitida pela política, a seguinte mensagem será exibida no GitHub:

O codespace não pode ser criado porque a imagem especificada na configuração do contêiner de desenvolvimento não é permitida. Talvez seja necessário selecionar um branch diferente, modificar a configuração do contêiner ou ajustar a configuração de política da sua organização.

Usando a CLI, a mensagem de erro é:

erro ao criar codespace: HTTP 400: A imagem base 'IMAGE-REFERENCE' não é permitida com base em uma política de organização definida pelo administrador da organização.

Se a imagem de um codespace for especificada em um Dockerfile e não corresponder à política, um codespace será criado no modo de recuperação, usando o contêiner de recuperação padrão em vez da imagem especificada. Uma mensagem nesse sentido é incluída no final do log de criação. Para saber mais sobre o log de criação, confira Logs do GitHub Codespaces.

Definindo políticas específicas da organização e do repositório

Ao criar uma política, você define se ela se aplica a todos os repositórios da organização ou apenas a repositórios específicos. Se você definir uma política para toda a organização, todas as políticas que você definir para repositórios individuais devem estar dentro da restrição definida no nível da organização. A adição de políticas torna a escolha da imagem mais restritiva.

Por exemplo, você pode criar uma política em toda a organização que restringe a imagem base a qualquer uma das dez imagens especificadas. Em seguida, você pode definir uma política para o Repositório A que restringe a imagem a um subconjunto de apenas duas das imagens especificadas no nível da organização. A especificação de imagens adicionais para o Repositório A não terá efeito porque essas imagens não são especificadas na política no nível da organização. Se adicionar uma política para toda a organização, você deverá configurá-la para a maior escolha de imagens que estarão disponíveis para qualquer repositório na sua organização. Em seguida, você pode adicionar políticas específicas ao repositório para restringir ainda mais a escolha.

Adicionando uma política para definir as imagens permitidas

1. No canto superior direito de GitHub, selecione sua foto de perfil e selecione Suas organizações.

2. Ao lado da organização, clique em Configurações.

3. Na seção "Código, planejamento e automação" da barra lateral, selecione Codespaces e clique em Políticas.

4. Na página "Políticas de codespaces", clique em Criar Política.

5. Insira um nome para sua nova política.

6. Clique em Adicionar restrição e escolha Imagens base.

7. Clique em para editar a restrição.

8. No campo "Valores permitidos", insira a referência de imagem da imagem do Docker que você deseja permitir.

   

   Você pode usar o curinga * como o último caractere da referência de imagem para corresponder a todas as imagens que começam com a mesma referência à esquerda do curinga. Por exemplo, mcr.microsoft.com/devcontainers/*.

9. Clique em para adicionar o valor.

10. Se necessário, repita as duas etapas anteriores para adicionar mais referências de imagem.

    Ao adicionar várias referências de imagem, se uma referência de imagem especificada na configuração do contêiner de desenvolvimento de um repositório não corresponder a nenhuma das referências em uma política aplicável ao repositório, você não poderá criar codespaces para esse repositório.

11. Clique fora da caixa de diálogo para fechá-la.

12. Por padrão, a política é definida para ser aplicada a todos os repositórios. Se você quiser que ela se aplique somente a alguns dos repositórios na sua organização, clique em Todos os repositórios e em Repositórios selecionados no menu suspenso.

    

    Note

    Se você estiver adicionando uma restrição a uma política existente que já contém a restrição "Maximum codespaces per user", não poderá aplicar a política aos repositórios selecionados. Isso ocorre porque a restrição "Máximo de coderspaces por usuário" sempre se aplica a todos os repositórios na organização.

    Com a opção Repositórios selecionados marcada:

    1. Clique em .

       

    2. Selecione os repositórios aos quais você quer que esta política seja aplicada.

    3. Na parte inferior da lista de repositórios, clique em Selecionar repositórios.

       

13. Para adicionar outra restrição à política, clique em Adicionar restrição e escolha outra restrição. Para obter informações sobre outras restrições, confira:

    • Restringindo o acesso aos tipos de máquina
    • Restringir o número de codespaces cobrados pela organização que um usuário pode criar
    • Como restringir a visibilidade das portas encaminhadas
    • Restringir o período de tempo limite ocioso
    • Como restringir o período de retenção de codespaces

14. Depois de concluir a adição de restrições à política, clique em Salvar.

A política é aplicada quando qualquer pessoa tenta criar um codespace que pode ser cobrado para sua organização. A restrição de imagem base não afeta os codespaces existentes, ativos ou parados.

Editando uma política

Você pode excluir ou editar uma política existente. Por exemplo, você talvez queira adicionar restrições a ou removê-las de uma política.

1. Exibir a página "Políticas de codespaces". Para saber mais, confira Como adicionar uma política para definir as imagens permitidas.
2. Clique no nome da política que você deseja editar.
3. Ao lado da restrição "Base de imagens", clique em .
4. Adicionar ou remover referências de imagens.
5. Clique em Save (Salvar).

Excluindo uma política

1. Exibir a página "Políticas de codespaces". Para saber mais, confira Como adicionar uma política para definir as imagens permitidas.

2. Clique em à direita da política que você deseja excluir.