Working with the Container registry

About the Container registry

O Container registry armazena imagens de contêiner na sua conta pessoal ou de organização e permite que você associe uma imagem a um repositório. Você pode escolher se deve herdar permissões de um repositório ou definir permissões granulares, independentemente de um repositório. Você também pode acessar imagens de contêiner público anonimamente.

To use the Container registry on GitHub Enterprise Server, your site administrator must first configure GitHub Packages for your instance and enable subdomain isolation. For more information, see "Getting started with GitHub Packages for your enterprise" and "Enabling subdomain isolation."

About Container registry support

The Container registry currently supports the following container image formats:

• Docker Image Manifest V2, Schema 2
• Open Container Initiative (OCI) Specifications

When installing or publishing a Docker image, the Container registry supports foreign layers, such as Windows images.

Authenticating to the Container registry

To authenticate to the Container registry (ghcr.io) within a GitHub Actions workflow, use the GITHUB_TOKEN for the best security and experience. Se o seu fluxo de trabalho estiver usando um PAT (token de acesso pessoal) para se autenticar em um registro, então é altamente recomendável atualizar seu fluxo de trabalho para usar o GITHUB_TOKEN.

Para obter mais informações sobre o GITHUB_TOKEN, confira "Autenticação em um fluxo de trabalho".

Para obter mais informações sobre as melhores práticas ao usar um registro em ações, confira "Proteção de segurança para GitHub Actions".

Ensure that you replace HOSTNAME with your GitHub Enterprise Server instance hostname or IP address in the examples below.

1. Crie um novo token de acesso pessoal (PAT) com os escopos apropriados para as tarefas que você deseja realizar. Se sua organização exigir SSO, você deverá habilitar o SSO para seu novo token.

   Observação: por padrão, quando você selecionar o escopo write:packages do PAT (token de acesso pessoal) na interface do usuário, o escopo repo também será selecionado. O escopo repo oferece acesso desnecessário e amplo, o qual, em particular, recomendamos que você evite usar para fluxos de trabalho do GitHub Actions. Para obter mais informações, confira "Proteção de segurança do GitHub Actions". Como solução alternativa, você pode selecionar apenas o escopo write:packages do PAT na interface do usuário com esta URL: https://HOSTNAME/settings/tokens/new?scopes=write:packages.

   • Selecione o escopo read:packages para baixar imagens de contêiner e ler os metadados dela.
   • Selecione o escopo write:packages para baixar e carregar imagens de contêiner e ler e gravar os metadados dela.
   • Selecione o escopo delete:packages para excluir imagens de contêiner.

   Para obter mais informações, confira "Como criar um token de acesso pessoal para a linha de comando".

2. Salve seu PAT. Recomendamos salvar o seu PAT como uma variável de ambiente.

   $ export CR_PAT=YOUR_TOKEN

3. Usando a CLI para o tipo de contêiner, entre no serviço do Container registry em containers.HOSTNAME.

   $ echo $CR_PAT | docker login containers.HOSTNAME -u USERNAME --password-stdin
   > Login Succeeded

Pushing container images

This example pushes the latest version of IMAGE_NAME.

$ docker push containers.HOSTNAME/OWNER/IMAGE_NAME:latest

This example pushes the 2.5 version of the image.

$ docker push containers.HOSTNAME/OWNER/IMAGE_NAME:2.5

When you first publish a package, the default visibility is private. To change the visibility or set access permissions, see "Configuring a package's access control and visibility."

Pulling container images

Pull by digest

To ensure you're always using the same image, you can specify the exact container image version you want to pull by the digest SHA value.

1. To find the digest SHA value, use docker inspect or docker pull and copy the SHA value after Digest:

   $ docker inspect containers.HOSTNAME/OWNER/IMAGE_NAME

2. Remove image locally as needed.

   $ docker rmi  containers.HOSTNAME/OWNER/IMAGE_NAME:latest

3. Pull the container image with @YOUR_SHA_VALUE after the image name.

   $ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs

Pull by name

$ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME

Pull by name and version

Docker CLI example showing an image pulled by its name and the 1.14.1 version tag:

$ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME:1.14.1
  > 5e35bd43cf78: Pull complete
  > 0c48c2209aab: Pull complete
  > fd45dd1aad5a: Pull complete
  > db6eb50c2d36: Pull complete
  > Digest: sha256:ae3b135f133155b3824d8b1f62959ff8a72e9cf9e884d88db7895d8544010d8e
  > Status: Downloaded newer image for containers.HOSTNAME/orgname/image-name/release:1.14.1
  > containers.HOSTNAME/orgname/image-name/release:1.14.1

Pull by name and latest version

$ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME:latest
  > latest: Pulling from user/image-name
  > Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344
  > Status: Downloaded newer image for containers.HOSTNAME/user/image-name:latest
  > containers.HOSTNAME/user/image-name:latest

Building container images

This example builds the hello_docker image:

$ docker build -t hello_docker .

Tagging container images

1. Find the ID for the Docker image you want to tag.

   $ docker images
   > REPOSITORY                                            TAG                 IMAGE ID            CREATED             SIZE
   > containers.HOSTNAME/my-org/hello_docker         latest              38f737a91f39        47 hours ago        91.7MB
   > containers.HOSTNAME/my-username/hello_docker    latest              38f737a91f39        47 hours ago        91.7MB
   > hello-world                                           latest              fce289e99eb9        16 months ago       1.84kB

2. Tag your Docker image using the image ID and your desired image name and hosting destination.

   $ docker tag 38f737a91f39 containers.HOSTNAME/OWNER/NEW_IMAGE_NAME:latest

Labelling container images

You can use Docker labels to add metadata including a description, a license, and a source repository to your container image. For more information on Docker labels, see LABEL in the official Docker documentation and Pre-Defined Annotation Keys in the opencontainers/image-spec repository.

The following labels are supported in the Container registry. Supported labels will appear on the package page for the image.

Label	Description
org.opencontainers.image.source	The URL of the repository associated with the package. For more information, see "Connecting a repository to a package."
org.opencontainers.image.description	A text-only description limited to 512 characters. This description will appear on the package page, below the name of the package.
org.opencontainers.image.licenses	An SPDX license identifier such as "MIT," limited to 256 characters. The license will appear on the package page, in the "Details" sidebar. For more information, see SPDX License List.

To add labels to an image, we recommend using the LABEL instruction in your Dockerfile. For example, if you're the user monalisa and you own my-repo, and your image is distributed under the terms of the MIT license, you would add the following lines to your Dockerfile:

LABEL org.opencontainers.image.source=https://HOSTNAME/monalisa/my-repo
LABEL org.opencontainers.image.description="My container image"
LABEL org.opencontainers.image.licenses=MIT

Alternatively, you can add labels to an image at buildtime with the docker build command.

$ docker build \
 --label "org.opencontainers.image.source=https://HOSTNAME/monalisa/my-repo" \
 --label "org.opencontainers.image.description=My container image" \
 --label "org.opencontainers.image.licenses=MIT"