Skip to main content

Permitir que seu codespace acesse um registro de imagens privadas

Você pode usar segredos para permitir que o GitHub Codespaces acesse um registro de imagens privadas

Sobre registros de imagens privadas e o GitHub Codespaces

Um registro é um espaço seguro para armazenar, gerenciar e buscar imagens privadas de contêineres. Você pode usar uma para armazenar uma ou mais imagens. Existem muitos exemplos de registros, como Container registry, npm registry, Registro de Contêiner do Azure ou DockerHub.

O Container registry and npm registry pode ser configurado para permitir que imagens de contêiner sejam puxadas diretamente para GitHub Codespaces durante a criação do codespace, sem precisar fornecer credenciais de autenticação. Para outros registros de imagem, você deve criar segredos em GitHub para armazenar os detalhes de acesso, o que permitirá que GitHub Codespaces acesse imagens armazenadas nesse registro.

Acessar imagens armazenadas no Container registry and npm registry

O Container registry and npm registry fornece a maneira mais fácil para o GitHub Codespaces consumir imagens do contêiner de desenvolvimento.

Para obter mais informações, confira "Como trabalhar com o registro de contêiner" e "Como trabalhar com o registro npm".

Acessar uma imagem publicada no mesmo repositório que o codespace

Se você publicar uma imagem de contêiner no Container registry or npm registry no mesmo repositório em que o codespace está sendo lançado, você poderá buscar automaticamente essa imagem na criação de um codespace. Você não precisará fornecer nenhuma credencial adicional, a menos a opção Herdar acesso do repositório tenha sido desmarcada quando a imagem de contêiner foi publicada.

Herdando acesso a partir do repositório no qual uma imagem foi publicada

Por padrão, quando você publica uma imagem de contêiner no Container registry or npm registry, a imagem herda as configurações de acesso do repositório do qual foi publicada. Por exemplo, se o repositório for público, a imagem também é pública. Se o repositório for privado, a imagem também é privada, mas pode ser acessada a partir do repositório.

Esse comportamento é controlado pela opção Herdar acesso do repositório. A opção Herdar acesso do repositório está selecionada por padrão na publicação por meio de GitHub Actions, mas não ao publicar diretamente no Container registry or npm registry usando um personal access token.

Se a opção Herdar acesso do repositório não estava selecionada quando a imagem foi publicada, adicione o repositório manualmente aos controles de acesso da imagem de contêiner publicada. Para obter mais informações, confira "Como configurar o controle de acesso e a visibilidade de um pacote".

Ao acessar uma imagem publicada na organização, um codespace será lançado em

Se você deseja que uma imagem de contêiner possa ser acessada por todos os codespaces em uma organização, recomendamos que você publique a imagem do contêiner com visibilidade interna. Isso tornará a imagem visível automaticamente para todos os códigos dentro da organização, a menos que o repositório no qual o código é iniciado seja público.

Se o codespace for lançado a partir de um repositório público que faz referência uma imagem interna ou privada, você deverá permitir manualmente o acesso do repositório público à imagem interna do contêiner. Isto impede que a imagem interna seja acidentalmente divulgada publicamente. Para obter mais informações, confira "Como garantir que os codespaces acessem seu pacote".

Acessar um contêiner privado a partir de um subconjunto de repositórios em uma organização

Se você deseja permitir que um subconjunto de repositórios de uma organização acesse uma imagem de contêiner ou permitir que uma imagem interna ou privada seja acessada por meio de um codespace iniciado em um repositório público, adicione repositórios manualmente às configurações de acesso da imagem de um contêiner. Para obter mais informações, confira "Como garantir que os codespaces acessem seu pacote".

Publicando uma imagem de contêiner a partir de um codespace

O acesso seguro de um codespace ao Container registry or npm registry é limitado à extração de imagens de contêineres. Se você deseja publicar uma imagem de contêiner por meio de um codespace, use um personal access token (classic) com o escopo write:packages.

Recomendamos publicar imagens via GitHub Actions. Para obter mais informações, confira "Como publicar imagens do Docker" e "Como publicar pacotes Node.js".

Acessando as imagens armazenadas em outros registros de contêiner

Se estiver acessando uma imagem de contêiner a partir de um registro que não é um Container registry or npm registry, o GitHub Codespaces verificará a presença de três segredos, que definem o nome de servidor, nome de usuário e personal access token para um registro de contêiner. 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 "Como gerenciar segredos criptografados para seus codespaces" e "Como gerenciar segredos criptografados para seu repositório e sua organização para o GitHub Codespaces".

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ê irá criar o codespace, escolhendo uma política de acesso na lista suspensa.

Exemplo de segredo do registro de imagem

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.

Exemplo de segredo do registro de imagem

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 "Como suspender ou parar um codespace".

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 egetuar 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 você não quiser que o GitHub execute a troca de credenciais em seu nome, você poderá fornecer um token de autorização obtido por meio das APIs ou da CLI do 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 de prioridade no servidor para obter uma imagem do 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.