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 saber mais, 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 saber mais, 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 saber mais, 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 saber mais, 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 saber mais, 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.
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.
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 saber mais, 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:
- DockerHub -
https://index.docker.io/v1/ - Registro de Contêiner do GitHub -
ghcr.io - Registro de Contêiner do Azure -
<registry name>.azurecr.io - AWS Elastic Container Registry -
<aws_account_id>.dkr.ecr.<region>.amazonaws.com - Google Cloud Container Registry -
gcr.io(EUA),eu.gcr.io(UE),asia.gcr.io(Ásia)
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.