Skip to main content

Como permitir que seu codespace acesse um registro privado

Você pode permitir que GitHub Codespaces acesse imagens de contêiner ou outros pacotes em um registro privado.

Sobre registros privados e GitHub Codespaces

Um registro é um espaço seguro para armazenar, gerenciar e buscar imagens de contêiner ou outros pacotes. Há muitos exemplos de registros, como:

  • Container registry do GitHub, o Registro de Contêiner do Azure e o DockerHub para imagens de contêiner
  • O npm registry para pacotes do Node.js.

Certos registros do GitHub Packages, incluindo o Container registry, podem ser configurados para permitir que os pacotes sejam extraídos sem problemas para GitHub Codespaces durante a criação do codespace, sem precisar fornecer nenhuma credencial de autenticação.

Para acessar outros registros de imagem de contêiner, você pode criar segredos no GitHub para armazenar os dados de acesso, o que permitirá que o GitHub Codespaces acesse as imagens armazenadas nesse registro.

Como acessar pacotes armazenados em registros com permissões granulares

Registros GitHub Packages que dão suporte a permissões granulares, incluindo o Container registry, fornecem a maneira mais fácil para o GitHub Codespaces consumir pacotes. Para ver a lista de registros do GitHub Packages que dão suporte a permissões granulares e acesso contínuo ao GitHub Codespaces, confira "Sobre permissões para o GitHub Packages".

Como acessar um pacote publicado no mesmo repositório que o codespace

Se você publicar um pacote no mesmo repositório em que o codespace está sendo iniciado, será possível buscar automaticamente esse pacote na criação do codespace. Você não precisará fornecer nenhuma credencial adicional, a menos que a opção Herdar acesso do repositório tenha sido desmarcada quando o pacote foi publicado.

Herdar o acesso do repositório do qual um pacote foi publicado

Por padrão, o pacote herda a configuração de acesso do repositório do qual foi publicado. Por exemplo, se o repositório for público, o pacote também será público. Se o repositório for privado, o pacote também será privado, mas acessível a partir do repositório.

Esse comportamento é controlado pela opção Herdar acesso do repositório. Herdar acesso do repositório é selecionado por padrão ao publicar por meio de GitHub Actions, mas não ao publicar diretamente em um registro usando um personal access token.

Se a opção Herdar acesso do repositório não foi selecionada quando o pacote foi publicado, você poderá adicionar manualmente o repositório aos controles de acesso do pacote publicado. Para obter mais informações, confira "Configurando o controle de acesso e visibilidade de um pacote".

Acessar um pacote publicado para a organização na qual um codespace será inicializado

Se você deseja que um pacote seja acessível a todos os codespaces em uma organização, recomendamos que você publique o pacote com visibilidade interna. Isso tornará o pacote automaticamente visível para todos os codespaces dentro da organização, a menos que o repositório do qual o codespace é inicializado seja público.

Se o codespace estiver sendo inicializado de um repositório público referenciando um pacote interno ou privado, você deverá permitir manualmente o acesso do repositório público ao pacote interno. Isso evita que o pacote interno vaze acidentalmente para o público. Para obter mais informações, confira "Configurando o controle de acesso e visibilidade de um pacote".

Acessar um pacote privado de um subconjunto de repositórios em uma organização

Se você deseja permitir que um subconjunto dos repositórios de uma organização acesse um pacote, ou permitir que um pacote interno ou privado seja acessado de um codespace inicializado em um repositório público, você pode adicionar repositórios manualmente às configurações de acesso de um pacote. Para obter mais informações, confira "Configurando o controle de acesso e visibilidade de um pacote".

Como publicar um pacote de um codespace

O acesso contínuo de um codespace para um registro é limitado a efetuar pull de pacotes. Se você deseja publicar um pacote de dentro de um codespace, deve usar um personal access token (classic) com o escopo write:packages.

Recomendamos a publicação de pacotes via GitHub Actions. Para obter mais informações, confira "Publicando imagens do Docker" e "Publicar pacotes do Node.js."

Como acessar imagens armazenadas em outros registros

Você pode definir segredos para permitir que o GitHub Codespaces acesse registros de imagem de contêiner que não sejam Container registry do GitHub. Se você estiver acessando uma imagem de contêiner de um registro que não oferece suporte ao acesso contínuo, o GitHub Codespaces verificará a presença de três segredos, que definirão o nome do servidor, nome de usuário e personal access token para um registro. Se esses segredos forem encontrados, o GitHub Codespaces disponibilizará o registro dentro do seu codespace.

  • <*>_CONTAINER_REGISTRY_SERVER
  • <*>_CONTAINER_REGISTRY_USER
  • <*>_CONTAINER_REGISTRY_PASSWORD

É possível armazenar segredos a nível do usuário, repositório ou organização, permitindo que você os compartilhe de forma segura entre diferentes codespaces. Ao criar um conjunto de segredos para um registro de imagem privado, você deverá substituir o "<*>" no nome por um identificador consistente. Para obter mais informações, confira "Gerenciando segredos específicos da sua conta para o GitHub Codespaces" e "Gerenciando segredos do ambiente de desenvolvimento para seu repositório ou organização."

Se você estiver definindo os segredos no nível do usuário ou da organização. certifique-se de atribuir esses segredos para o repositório no qual você criará o codespace, escolhendo uma política de acesso na lista suspensa.

Screenshot of the "Repository access" dropdown menu with the options "All repositories," "Private repositories," and "Selected repositories."

Transferir uma imagem do Docker para o seu codespace

Como o GitHub Codespaces usa o Docker, se você quiser transferir uma imagem privada do Docker dentro do seu codespace em runtime, será necessário usar o Docker-in-Docker. Para tornar isso possível, os segredos necessários para o login no Docker são adicionados automaticamente ao arquivo ~/.docker/config.json dentro do codespace. Isso acontece após o gancho de ciclo de vida onCreateCommand, mas antes de postCreateCommand, postStartCommand e postAttachCommand. Como resultado, o postCreateCommand conseguirá usar o Docker-in-Docker para transferir uma imagem do Docker para o codespace, mas isso não será possível para o onCreateCommand. Por esse motivo, o Docker-in-Docker não fica disponível durante a criação de uma pré-compilação.

Depois que o codespace estiver em execução, você conseguirá abrir um terminal nele e executar o comando docker pull PRIVATE-IMAGE-URL.

Exemplos de segredos

Para uma lista de imagens privadas no Azure, você pode criar os seguintes segredos:

ACR_CONTAINER_REGISTRY_SERVER = mycompany.azurecr.io
ACR_CONTAINER_REGISTRY_USER = acr-user-here
ACR_CONTAINER_REGISTRY_PASSWORD = <PERSONAL_ACCESS_TOKEN>

Para obter informações sobre registros de imagem comuns, confira "Servidores de registro de imagem comuns". Observe que acessar o AWS Elastic Container Registry (ECR) é diferente.

Captura de tela das configurações de "Segredos de Codespaces" para um repositório. Três segredos para o Registro de Contêiner do ACR são definidos.

Após adicionar os segredos, pode ser que você precise parar e, em seguida, iniciar o processo de codespace para que as novas variáveis de ambiente sejam passadas para o contêiner. Para obter mais informações, confira "Uso da paleta de comandos do Visual Studio Code no GitHub Codespaces".

Acessando o AWS Elastic Container Registry

Para acessar o AWS Elastic Container Registry (ECR), você pode fornecer o ID de uma chave de acesso do AWS e a chave do segredo e GitHub poderá obter um token de acesso para você e efetuar o login em seu nome.

*_CONTAINER_REGISTRY_SERVER = <ECR_URL>
*_CONTAINER_REGISTRY_USER = <AWS_ACCESS_KEY_ID>
*_CONTAINER_REGISTRY_PASSWORD = <AWS_SECRET_KEY>

Você também precisa garantir que tenha as permissões apropriadas de IAM da AWS para fazer a troca de credenciais (por exemplo, sts:GetServiceBearerToken), bem como a operação de leitura do ECR (AmazonEC2ContainerRegistryFullAccess ou ReadOnlyAccess).

Como alternativa, se não quiser que GitHub execute a troca de credenciais em seu nome, você poderá fornecer um token de autorização obtido por APIs ou a CLI da AWS.

*_CONTAINER_REGISTRY_SERVER = <ECR_URL>
*_CONTAINER_REGISTRY_USER = AWS
*_CONTAINER_REGISTRY_PASSWORD = <TOKEN>

Como esses tokens são curtos e precisam ser atualizados periodicamente, recomendamos fornecer um ID de chave de acesso e um segredo.

Embora esses segredos possam ter qualquer nome, desde que o *_CONTAINER_REGISTRY_SERVER seja uma URL do ECR, recomendamos usar ECR_CONTAINER_REGISTRY_*, a menos que você esteja lidando com vários registros do ECR.

Para obter mais informações, confira a "documentação de autenticação de registro privado" do ECR da AWS.

Servidores de registro de imagens comuns

Alguns dos servidores comuns de registro de imagens estão listados abaixo:

Depurando o acesso ao registro de imagens privadas

Se você tendo problemas para extrair uma imagem de um registro de imagem privada, verifique se consegue executar docker login -u <user> -p <password> <server> usando os valores dos segredos definidos acima. Se o login falhar, certifique-se de que as credenciais de login sejam válidas e que você tenha as permissões apropriadas no servidor para buscar uma imagem de contêiner. Se o login for bem-sucedido, certifique-se de que esses valores são copiados adequadamente para os segredos de GitHub Codespaces corretos, seja no nível de usuário, repositório ou organização e tente novamente.