Skip to main content

Como restringir a imagem base dos codespaces

Você pode especificar quais imagens base podem ser usadas para novos codespaces criados em sua organização.

Quem pode usar esse recurso?

To manage image constraints for an organization's codespaces, you must be an owner of the organization.

As organizações com os planos do GitHub Team e do GitHub Enterprise podem pagar pelo uso de membros e colaboradores do GitHub Codespaces. Depois, essas organizações podem acessar configurações e políticas para gerenciar codespaces pagos pela organização. Para obter mais informações, confira "Como escolher quem tem a propriedade e paga pelos codespaces em sua organização" e "Planos do GitHub."

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 obter mais informações, 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.

JSON
"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 obter mais informações, 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 obter mais informações, 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.com:

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".

Observações:

  • A imagem base do contêiner de desenvolvimento não deve ser confundida com a imagem do host. A imagem do host é a imagem usada para criar a máquina virtual na qual o contêiner de desenvolvimento é executado. Para obter mais informações, confira "Escolher a imagem do host estável ou beta".
  • A política de imagem base é aplicada quando um codespace é criado e quando você executa uma reconstrução de contêiner completo. Para obter mais informações, confira "Noções básicas sobre o ciclo de vida do codespace".
  • A política de imagem base não se aplicará à imagem padrão ou à imagem usada para recuperar um codespace se, em uma configuração de contêiner de desenvolvimento, for introduzido um erro que impeça a recriação do contêiner.

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.

Observação: políticas de codespaces só se aplicam a codespaces pagos por sua organização. Se alguém criar um codespace para um repositório na sua organização por conta própria, o codespace não será associado a essas políticas. Para obter mais informações, confira "Como escolher quem tem a propriedade e paga pelos codespaces em sua organização".

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.

    Captura de tela da referência de imagem "mcr.microsoft.com/devcontainers/java" inserida no campo "Valores permitidos".

    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.

    Captura de tela do menu suspenso de seleção de repositório, mostrando as opções "Todos os repositórios" e "Repositórios selecionados".

    Observação: se você estiver adicionando uma restrição a uma política existente que já contém a restrição "Máximo de codespaces por usuário", 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 .

      Captura de tela do ícone de configurações (um símbolo de engrenagem) à esquerda de um botão denominado "Repositórios selecionados".

    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.

      Captura de tela de uma lista de repositórios, cada um com uma caixa de seleção. Três repositórios são selecionados.

  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:

  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 obter mais informações, 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 obter mais informações, confira "Como adicionar uma política para definir as imagens permitidas".

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

    Captura de tela de uma política com o botão Excluir (um ícone de lixeira) realçado com uma estrutura de tópicos laranja escura.